Restful API Naming Convention Meeting Minutes

Meeting Info ¶

Meeting Agenda ¶

1. Recap of documentation rules (5 mins)
2. Review UAS wiki (10 mins)
3. Discussion on Restful API Naming Convention (30 min)

Meeting Minutes ¶

Recap of documentation rules ¶

Mainly talked about the documentations about basic guideline, structure guideline, and style guide. Wiki doc need pull request and review. Weekly plan meeting should evaluate whether the task needs document. The documents for internal engineers and clients are different. So, it should be more specific for internal users. In term of the style guide, Rocky sketched the details of each rule.

Review the UAS wiki ¶

Ted demonstrated the new UAS wiki. The whole structure of this wiki looks great. Moreover, team members gave several suggestions. Some title should follow the markdown title style. We should use the specific types when adding some code examples in document. The current alert service wiki is supposed to be moved to the new UAS wiki.

Discussion on Restful API Naming Convention ¶

• The POST method is most-often utilized to create new resources. On successful creation, return HTTP status 201. In an error case, it most often returns a 404 (Not Found), 409 (Conflict) if resource already exists. [Mandatory]

Comments: The current status codes of MCT are nonstandard. All response status codes now are 200. Body response type should be JSON.

• The HTTP GET method is used to read (or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). [Mandatory]

Comments: Get method is used to read. Do not use GET to delete.

• The PUT method is most-often utilized for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful update, return HTTP status 200 (OK) or 204 (No Content). In an error case, it most often returns a 404 (Not Found), if ID not found or invalid. [Mandatory]

Comments: PATCH is used to modify part of the data. Please use PUT instead of PATCH.

• The PATCH method is used for modify capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource. On successful modification, return HTTP status 200 (OK) or 204 (No Content). In an error case, it most often returns a 404 (Not Found), if ID not found or invalid. [Reference]

• The DELETE method is pretty easy to understand. It is used to delete a resource identified by a URI. On successful deletion, return HTTP status 200 (OK) along with a response body. In an error case, it most often returns a 404 (Not Found), if ID not found or invalid. [Mandatory]

• If there are multiple word unions in URI, we suggest to use - to split and link. [Mandatory]

Comments: Use ‘-‘ to replace camelCase in request URI.

• If it is a GET method Restful API, we should not have "query", "get" and other verbs in URI. [Mandatory]

• If it is a DELETE method Restful API, we should not have "delete" and other verbs in URI. [Mandatory]

• If it is a POST method Restful API, we don't suggest to have "create" and other verbs in URI. [Recommended]

Comments: For the 7th, 8th, and 9th rules, do not use verbs in URI.

• We should define @NotNull or have validation in function for someone QueryParam parameter if it is required. [Mandatory]

Comments: Use PathParam if it is Mandatory

• We should have a standard and same json body structure (Vue new UI framework required) for all of Restful APIs return. Like return error code, we need to define accurately. [Mandatory]