Merge "REST API specification for product management."
This commit is contained in:
Jenkins
Gerrit Code Review
commit
1c1ed4bf89
412
specs/mitaka/approved/product-registration-api.rst
Executable file
412
specs/mitaka/approved/product-registration-api.rst
Executable file
@ -0,0 +1,412 @@
|
||||
Launchpad blueprint: https://blueprints.launchpad.net/refstack/+spec/vendor-result-validation
|
||||
|
||||
Requirement document: https://goo.gl/bvo4FG
|
||||
|
||||
Data model document: https://goo.gl/zWYnoq
|
||||
|
||||
Based on the blueprint and requirement documents listed above, this spec
|
||||
defines the REST APIs needed to support the product registration process.
|
||||
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
As RefStack implements the vendor and product registration process, additional
|
||||
REST APIs are needed for management of the newly added entities. This spec
|
||||
will focus on the product management APIs.
|
||||
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Add new REST APIs to to RefStack v1 API support the following:
|
||||
|
||||
* Create a product
|
||||
|
||||
Any RefStack authenticated user can create a product.
|
||||
|
||||
* Delete a product
|
||||
|
||||
Foundation admins or admins in this vendor can delete the product records.
|
||||
|
||||
* Update a product record
|
||||
|
||||
Foundation admins or admins in this vendor can make update to the product
|
||||
records.
|
||||
|
||||
* List product
|
||||
|
||||
All RefStack users can list (view) publicly available product records with
|
||||
limited details. Foundation admins and vendor admins can retrieve full
|
||||
detail information of the products.
|
||||
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
Direct access to the database to retrieve test records. Open to suggestions.
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
|
||||
The following REST APIs will be added to RefStack.
|
||||
|
||||
**List products**
|
||||
|
||||
* Description:
|
||||
|
||||
This API will be used to list the products in RefStack. By default, the
|
||||
response will include all product records that the user has privilege to
|
||||
retrieve. The result list will be sorted by names in alphabetical ascending
|
||||
order. At the time of this writing, the number of products will be
|
||||
registered in RefStack is expected to be small. Therefore, no
|
||||
result-limiting features such as pagination or filtering is implemented.
|
||||
More sophisticated filter, sorting and pagination features may be added in
|
||||
the future.
|
||||
|
||||
**Note:** A "list products with detail" REST API will also be added later.
|
||||
Foundation and vendor admins can use this API to obtain additional private
|
||||
product information such as product record created date, created by user,
|
||||
etc.
|
||||
|
||||
* Method type: GET
|
||||
|
||||
* URI: v1/products/
|
||||
|
||||
* Normal Response Codes:
|
||||
|
||||
* OK (200)
|
||||
|
||||
* Error Response Codes:
|
||||
|
||||
* Bad Request (400)
|
||||
|
||||
* Request parameters: N/A
|
||||
|
||||
* JSON schema definition for the body data: N/A
|
||||
|
||||
* JSON schema definition for the response data:
|
||||
|
||||
This response may include all publicly shared and private product records
|
||||
that the requester has privilege to retrieve.
|
||||
|
||||
.. parsed-literal::
|
||||
{
|
||||
"products": [
|
||||
{
|
||||
"id" : "95346866-307f-4052-ba31-ff6270635e14",
|
||||
"name" : "Product ABC",
|
||||
"description" : "My description",
|
||||
"product_id" : "7e0072fb-a3e9-4901-82cd-9a3a911507d8",
|
||||
"product_type" : 1,
|
||||
"public" : 1,
|
||||
"type" : 0,
|
||||
"organization_id" : "69346866-307f-4052-ba31-ff6270635e19"
|
||||
},
|
||||
{
|
||||
"id" : "78346866-307f-4052-ba31-ff6270635e19",
|
||||
"name" : "Product EFG",
|
||||
"description" : "My description"
|
||||
"product_id" : "8c9u72fb-a3e9-4901-82cd-9a3a911507d8",
|
||||
"product_type" : 0,
|
||||
"public" : 1,
|
||||
"type" : 1,
|
||||
"organization_id" : "87346866-307f-4052-ba31-ff6270635e19"
|
||||
},
|
||||
{
|
||||
"id" : "12346866-307f-4052-ba31-ff6270635e19",
|
||||
"name" : "Product HIJ",
|
||||
"description" : "My description"
|
||||
"product_id" : "987672fb-a3e9-4901-82cd-9a3a911507d8",
|
||||
"product_type" : 2,
|
||||
"public" : 1,
|
||||
"type" : 0,
|
||||
"organization_id" : "77346866-307f-4052-ba31-ff6270635e19"
|
||||
},
|
||||
......
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
**Show product details**
|
||||
|
||||
* Description: This API will be used to retrieve the detail information of a
|
||||
particular product.
|
||||
* Method type: GET
|
||||
* URI: v1/products/{id}
|
||||
|
||||
* Normal Response Codes:
|
||||
|
||||
* OK (200)
|
||||
|
||||
* Error Response Codes:
|
||||
|
||||
* Bad Request (400)
|
||||
* Unauthorized (401)
|
||||
* Not found (404)
|
||||
|
||||
* Request parameters:
|
||||
|
||||
+---------------+-------+--------------+-----------------------------------+
|
||||
| Parameter | Style | Type | Description |
|
||||
+===============+=======+==============+===================================+
|
||||
| id | URI | csapi:UUID | ID to retrieve data. |
|
||||
+---------------+-------+--------------+-----------------------------------+
|
||||
|
||||
* JSON schema definition for the body data: N/A
|
||||
|
||||
* JSON schema definition for the response data:
|
||||
|
||||
The response data will be filtered depending on whether the requester is a
|
||||
foundation admin or an admin user of the vendor which owns the product.
|
||||
|
||||
* Response for non-foundation or none-vendor admins:
|
||||
|
||||
.. parsed-literal::
|
||||
{
|
||||
{
|
||||
"id" : "12346866-307f-4052-ba31-ff6270635e19",
|
||||
"name" : "Product HIG",
|
||||
"description" : "My description"
|
||||
"product_id" : "987672fb-a3e9-4901-82cd-9a3a911507d8",
|
||||
"product_type" : 2,
|
||||
"public" : 1,
|
||||
"type" : 0,
|
||||
"organization_id" : "77346866-307f-4052-ba31-ff6270635e19"
|
||||
}
|
||||
}
|
||||
|
||||
* Response for foundation or vendor admin users:
|
||||
|
||||
.. parsed-literal::
|
||||
{
|
||||
{
|
||||
"id" : "12346866-307f-4052-ba31-ff6270635e19",
|
||||
"name" : "Product HIG",
|
||||
"description" : "My description"
|
||||
"product_id" : "987672fb-a3e9-4901-82cd-9a3a911507d8",
|
||||
"product_type" : 2,
|
||||
"public" : 1,
|
||||
"properties" : "some text"
|
||||
"created_at": "2016-02-01 08:42:25",
|
||||
"created_by_user": "john@abc.com",
|
||||
"updated_at": "2016-02-02 08:42:25",
|
||||
"type" : 0,
|
||||
"organization_id" : "77346866-307f-4052-ba31-ff6270635e19"
|
||||
}
|
||||
}
|
||||
|
||||
**Create product**
|
||||
|
||||
* Description:
|
||||
|
||||
This API will be used to create a product in RefStack. Any RefStack
|
||||
authenticated user can create a product. Per current RefStack design, a
|
||||
product must be owned by a vendor. Therefore, if a vendor owner is not
|
||||
specified at the time when the product is created, a default private vendor
|
||||
will be created with the requester being assigned as the newly created
|
||||
vendor's admin user. By default, a product will be created as private.
|
||||
|
||||
* Method type: POST
|
||||
|
||||
* URI: v1/products/
|
||||
|
||||
* Normal Response Codes:
|
||||
|
||||
* Created (201)
|
||||
|
||||
* Error Response Codes:
|
||||
|
||||
* Bad Request (400)
|
||||
* Unauthorized (401)
|
||||
* Not found (404)
|
||||
|
||||
* Request parameters: N/A
|
||||
|
||||
* JSON schema definition for the body data:
|
||||
|
||||
.. parsed-literal::
|
||||
{
|
||||
"name" : "ABC",
|
||||
"description" : "My description"
|
||||
"product_type" : 2,
|
||||
"organization_id" : "95346866-307f-4052-ba31-ff6270635e14"
|
||||
"required": ["name", "product_type"]
|
||||
}
|
||||
|
||||
* JSON schema definition for the response data:
|
||||
|
||||
.. parsed-literal::
|
||||
{
|
||||
"id" : "345676866-307f-4052-ba31-ff6270635f20"
|
||||
}
|
||||
|
||||
**Update product**
|
||||
|
||||
* Description:
|
||||
|
||||
This API will be used to update the fields of a product in RefStack. Only
|
||||
foundation admins or admin users of this vendor can perform update on a
|
||||
product record.
|
||||
|
||||
* Method type: PUT
|
||||
|
||||
* URI: v1/products/{id}
|
||||
|
||||
* Normal Response Codes:
|
||||
|
||||
* OK (200)
|
||||
|
||||
* Error Response Codes:
|
||||
|
||||
* Bad Request (400)
|
||||
* Unauthorized (401)
|
||||
* Not found (404)
|
||||
|
||||
* Request parameters:
|
||||
|
||||
+---------------+-------+--------------+-----------------------------------+
|
||||
| Parameter | Style | Type | Description |
|
||||
+===============+=======+==============+===================================+
|
||||
| id | URI | csapi:UUID | ID for update. |
|
||||
+---------------+-------+--------------+-----------------------------------+
|
||||
|
||||
* JSON schema definition for the body data:
|
||||
|
||||
.. parsed-literal::
|
||||
{
|
||||
{
|
||||
"name" : "Product EFG",
|
||||
"description" : "My description"
|
||||
"product_id" : "987672fb-a3e9-4901-82cd-9a3a911507d8",
|
||||
"public" : 1,
|
||||
"properties" : "some text"
|
||||
"required": []
|
||||
}
|
||||
}
|
||||
|
||||
* JSON schema definition for the response data:
|
||||
|
||||
.. parsed-literal::
|
||||
{
|
||||
{
|
||||
"id" : "95346866-307f-4052-ba31-ff6270635e14",
|
||||
"name" : "Product EFG",
|
||||
"description" : "My description",
|
||||
"product_id" : "987672fb-a3e9-4901-82cd-9a3a911507d8",
|
||||
"product_type" : 2,
|
||||
"public" : 1,
|
||||
"properties" : "some text"
|
||||
"type" : 1,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
**Delete product**
|
||||
|
||||
* Description:
|
||||
|
||||
This API will be used to delete a product in RefStack. Foundation admins and
|
||||
admin users of this vendor can delete a product.
|
||||
|
||||
* Method type: DELETE
|
||||
|
||||
* URI: v1/products/{id}
|
||||
|
||||
* Normal Response Codes:
|
||||
|
||||
* No content (204)
|
||||
|
||||
* Error Response Codes:
|
||||
|
||||
* Bad Request (400)
|
||||
* Unauthorized (401)
|
||||
* Not found (404)
|
||||
|
||||
* Request parameters:
|
||||
|
||||
+---------------+-------+--------------+-----------------------------------+
|
||||
| Parameter | Style | Type | Description |
|
||||
+===============+=======+==============+===================================+
|
||||
| id | URI | csapi:UUID | ID to be removed. |
|
||||
+---------------+-------+--------------+-----------------------------------+
|
||||
|
||||
* JSON schema definition for the body data: N/A
|
||||
|
||||
* JSON schema definition for the response data: N/A
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
None.
|
||||
|
||||
Notifications impact
|
||||
--------------------
|
||||
|
||||
None.
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
None
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
None
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
None
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
None
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
Andrey Pavlov
|
||||
|
||||
Other contributors:
|
||||
TBD
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
* Create the REST APIs.
|
||||
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
None
|
||||
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
None
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
None
|
||||
Loading…
x
Reference in New Issue
Block a user