Overview
Under the principles of REST, here are some general conventions used by the InFocus API.
Endpoint Best Practices
Naming Conventions
Endpoints are nouns (e.g. Employee, Project, etc.) and should be listed in order of plural to singular based on specificity.
| • | /employees/{employee_code} |
Respones
Similarly, the data returned in an endpoint response should follow respectively from generic to detailed.
For example, a GET request to /employees would have a more generic response than the same request to /employees/{employee_code}
| • | GET /employees - Generic information for many records. (e.g. many rows, fewer columns). |
| • | GET /employees/{employee_code} - Detailed information for one record (e.g. single row, many columns). |
HTTP Methods
HTTP Methods are verbs and should follow these general conventions when making endpoint requests.
| • | GET - Retrieves records. Requests can be made to both plural and singular endpoints. As discussed above, responses should be generic or detailed respectively. |
| • | POST - Creates records. Requests are made to plural endpoints only and must define the criteria for INSERT in the body of the request. |
| • | PUT - Updates records. Requests are made to singular endpoints and must define the criteria for UPDATE in the body of the request. While it is possible to make a PUT request to a plural endpoint, this should be done with great caution. |
| • | DELETE - Deletes records. Requests are made to singular endpoints and must define the criteria for the DELETE in the body of the request. While it is possible to make a DELETE request to a plural endpoint, this should be done with great caution. |
|