refstack/specs/newton/implemented/vendor-registration-api.rst

Vendor Registration API

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 vendor registration process.

Problem description

As RefStack implements the vendor registration process, additional REST APIs are needed for management of the newly added entities such as product and vendor. Two categories of REST APIs will be created, one for vendor management (CRUD) and the other for product management. This spec will focus on the vendor management API.

The new APIs will be added to RefStack v1 API.

Proposed change

Add new REST APIs to support the following:

• Create a vendor

  Any RefStack authenticated user can create a vendor. By default, the vendor is of type "private" vendor when it is created.

• Delete a vendor

  Only foundation admins can delete official vendors. In addition, vendor admin users can delete own private/pending vendor.

• Update a vendor record

  Foundation admins or admins in this vendor can make update to the vendor records.

• List vendor

  All RefStack users can list (view) official vendor records with limited details. Foundation admins can retrieve full detail records of all vendors.

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 vendors

• Description:

  This API will be used to list the vendors in RefStack. By default, the response will include all vendor records that the user has privilege to retrieve. This list will be sorted by names in alphabetical ascending order. At the time of this writing, the number of vendor 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 vendors with detail" REST API will also be added later. Foundation and vendor admins can use this API to obtain more detail private vendor information such as vendor record created date, created user, etc.

• Method type: GET

• URI: v1/vendors/

• 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 official (public) vendors, the private and pending vendors that the requester has privilege to retrieve.

  { "vendors": [ { "id" : "95346866-307f-4052-ba31-ff6270635e14", "name" : "Vendor ABC", "description" : "My description", "type" : 3 }, { "id" : "78346866-307f-4052-ba31-ff6270635e19", "name" : "Vendor EFG", "description" : "My description", "type" : 1 }, ...... ] }

  Note: The values of the "type" filed are a set of pre-defined constants (enum) depicting the type of vendors. The constant definition can be found in https://github.com/openstack/refstack/blob/master/refstack/api/constants.py .

Show vendor details

• Description: This API will be used to retrieve the detail information of a particular vendor.

• Method type: GET

• URI: v1/vendors/{vendor_id}

• Normal Response Codes:

  • OK (200)

• Error Response Codes:

  • Bad Request (400)
  • Not found (404)

• Request parameters:

  Parameter	Style	Type	Description
  vendor_id	URI	csapi:UUID	Vendor 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 this vendor.

  • Response for non-foundation or vendor admins:

    { { "id" : "95346866-307f-4052-ba31-ff6270635e14", "name" : "Vendor ABC", "description" : "My description", "type" : 3 } }

  • Response for foundation or vendor admin users:

    { { "id" : "95346866-307f-4052-ba31-ff6270635e14", "name" : "Vendor ABC", "description" : "My description", "type" : 3, "created_at": "2016-02-01 08:42:25", "created_by_user": "john@abc.com", "updated_at": "2016-02-02 08:42:25", "properties" : "some text" } }

Create vendor

• Description:

  This API will be used to create a vendor in RefStack. By default the vendor will be created as a private vendor.

• Method type: POST

• URI: v1/vendors/

• Normal Response Codes:

  • Created (201)

• Error Response Codes:

  • Bad Request (400)
  • Unauthorized (401)

• Request parameters: N/A

• JSON schema definition for the body data:

  { "name" : "ABC", "description" : "My description", "required": ["name"] }

• JSON schema definition for the response data:

  { "id" : "95346866-307f-4052-ba31-ff6270635e14" }

Update vendor

• Description:

  This API will be used to update the fields of a vendor in RefStack. Only foundation admins or admin users of this vendor can perform update on a vendor record.

• Method type: PUT

• URI: v1/vendors/{vendor_id}

• Normal Response Codes:

  • OK (200)

• Error Response Codes:

  • Bad Request (400)
  • Unauthorized (401)
  • Not found (404)

• Request parameters:

  Parameter	Style	Type	Description
  vendor_id	URI	csapi:UUID	Vendor ID for update.

• JSON schema definition for the body data:

  { { "name" : "Vendor ABC", "description" : "My description", "properties" : "some text", "required": [] } }

• JSON schema definition for the response data:

  { { "id" : "95346866-307f-4052-ba31-ff6270635e14", "name" : "Vendor ABC", "description" : "My description", "type" : 3, "created_at" : "2016-02-01 08:42:25", "created_by_user": "john@abc.com", "updated_at" : "2016-02-02 08:42:25", "properties" : "some text" } }

Vendor action API

The action API is used to perform an action on the vendor object. The action is defined in the request body.

Register as an official vendor

• Description:

  This API will be used by the vendor admins to register a private vendor for foundation approval to become an official vendor.

• Method type: POST

• URI: v1/vendors/{vendor_id}/action

• Normal Response Codes:

  • OK (202)

• Error Response Codes:

  • Bad Request (400)
  • Unauthorized (401)
  • Not found (404)

• Request parameters:

  Parameter	Style	Type	Description
  vendor_id	URI	csapi:UUID	Vendor ID for update.
  register	plain	xsd:string	Action to request registering a private vendor to become an official vendor. vendor "type" will change from "private" to "pending"

• JSON schema definition for the body data:

  { "register" : null }

• JSON schema definition for the response data: N/A

Cancel submitted register request

• Description:

  This API will be used by the vendor admins to cancel previously submitted register requests.

• Method type: POST

• URI: v1/vendors/{vendor_id}/action

• Normal Response Codes:

  • OK (202)

• Error Response Codes:

  • Bad Request (400)
  • Unauthorized (401)
  • Not found (404)

• Request parameters:

  Parameter	Style	Type	Description
  vendor_id	URI	csapi:UUID	Vendor ID for update.
  cancel	plain	xsd:string	Action to request canceling a previously submitted register request. Vendor "type" will change from "pending" to "private".

• JSON schema definition for the body data:

  { "cancel" : null }

• JSON schema definition for the response data: N/A

Approve to become an official vendor

• Description:

  This API will be used by the foundation admins to apporove a vendor of type "pending" to become an official vendor.

• Method type: POST

• URI: v1/vendors/{vendor_id}/action

• Normal Response Codes:

  • OK (202)

• Error Response Codes:

  • Bad Request (400)
  • Unauthorized (401)
  • Not found (404)

• Request parameters:

  Parameter	Style	Type	Description
  vendor_id	URI	csapi:UUID	Vendor ID for update.
  approve	plain	xsd:string	Action to approve a vendor of type "pending" to "official"

• JSON schema definition for the body data:

  { "approve" : null }

• JSON schema definition for the response data: N/A

Deny to become an official vendor

• Description:

  This API will be used by the foundation admins to deny a vendor of type "pending" to become an official vendor.

• Method type: POST

• URI: v1/vendors/{vendor_id}/action

• Normal Response Codes:

  • OK (202)

• Error Response Codes:

  • Bad Request (400)
  • Unauthorized (401)
  • Not found (404)

• Request parameters:

  Parameter	Style	Type	Description
  vendor_id	URI	csapi:UUID	Vendor ID for update.
  deny	plain	xsd:string	Action to deny a vendor of type "pending" to "official". Vendor type will change from "pending" to "private".
  reason	plain	xsd:string	Reason for denial.

• JSON schema definition for the body data:

  { "deny" : null "reason" : "My reason for denial" }

• JSON schema definition for the response data: N/A

Delete vendor

• Description:

  This API will be used to delete a vendor in RefStack. Only foundation admins can delete an official (public) vendor. Foundation admins and admin users of this vendor can delete a private or pending vendor.

• Method type: DELETE

• URI: v1/vendors/{vendor_id}

• Normal Response Codes:

  • No content (204)

• Error Response Codes:

  • Bad Request (400)
  • Unauthorized (401)
  • Not found (404)

• Request parameters:

  Parameter	Style	Type	Description
  vendor_id	URI	csapi:UUID	Vendor 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