Adhere to RESTful Web Services conventions

[markborkum]

Pacifica Metadata version

1.0

Pacifica Core Software versions

n/a

Platform Details

All supported platforms.

Scenario:

Attempting to develop a client library for Pacifica Metadata Services endpoints using off-the-shelf components that adhere to RESTful Web Services conventions.

Steps to Reproduce:

n/a

Expected Result:

The expected result is for the specification and behavior of Pacifica Metadata Services endpoints to adhere to RESTful Web Services conventions for the create-read-update-delete (CRUD) record life-cycle. This way, off-the-shelf components can be used without modification.

The following examples are for User records, i.e., the /users endpoint.

Create

Path: /users
Request HTTP method: POST
Request data: HTTP query parameters specify attributes for new record
Response HTTP status code: 201 Created, or 4xx error
Response data: No response data

Read

Path: /users
Request HTTP method: GET
Request data: HTTP query parameters specify filtering, pagination and sorting behaviors
Response HTTP status code: 200 OK
Response data: JSON array of JSON objects

Path: /users/:id (where ":id" is a named capture group for the "id" attribute)
Request HTTP method: GET
Request data: No request data
Response HTTP status code: 200 OK
Response data: JSON object

Update

Path: /users/:id (where ":id" is a named capture group for the "id" attribute)
Request HTTP method: PATCH or PUT
Request data: HTTP query parameters specify attributes for modified record
Response HTTP status code: 202 Accepted, or 4xx error
Response data: No response data

Destroy

Path: /users/:id (where ":id" is a named capture group for the "id" attribute)
Request HTTP method: DELETE
Request data: No request data
Response HTTP status code: 202 Accepted, or 4xx error
Response data: No response data

Actual Result:

In metadata/rest/orm.py:

• Response HTTP status codes are not documented.
• Record creation and updating are done via HTTP PUT and POST requests, respectively. Adhering to conventions, these should be the other way around.
• Reading a record is done via the same mechanism as searching for a list of records. Adhering to conventions, each record should be uniquely identified via a URI whose resolution does not depend on HTTP query parameters.

[dmlb2000]

@markborkum Do you know if the conventions are documented anywhere in a spec? Swapping these would present a breaking change and I'd like to have the reason of, "Spec ... says you need to use X."

[dmlb2000]

https://stackoverflow.com/questions/6203231/which-http-methods-match-up-to-which-crud-methods Talks about that if the request is idempotent then it should map to PUT and anything else should map to POST. Though it also mentions that both methods should allow for updates if the item exists... But a stack exchange article is hardly a spec...

[dmlb2000]

https://en.wikipedia.org/wiki/Representational_state_transfer The wikipedia has a slightly different thought on the difference between POST and PUT, it just says one is not generally used... and it's PATCH that should be used... for individual objects. This article does differentiate between hitting the base object and an item with POST and PUT.

[dmlb2000]

https://tools.ietf.org/html/rfc2616#section-9.1.2 A lot of the difference between POST and PUT (and the other methods) are related to idempotence of the method. POST is not idempotent and PUT is supposed to be. However the second paragraph talks about side effects when doing a sequence of PUTs...

[dmlb2000]

Yeah I don't adhere to any of the above standards or conventions 100%, just kinda made up my own... Plan of attack should be to move the object level interactions to a /v1/users etc endpoints and do the appropriate REST style POST, PUT, PATCH, DELETE, GET, etc methods on that prefix.