API Guidelines

The following are some guidelines to be used when developing API’s. Keeping methods and responses consistent is very important for the consumers to understand the API.

HTTP Methods

GET:

GET is the most common HTTP methods. The client uses GET to request resources from the server. GET is safe, in that a GET request should never update any resources on the server (except logging information, etc).

Response codes used for GET:
200 OK
– returns the content from the GET request

PUT:

PUT is used to update a resource on the server. Generally, the use of PUT is a client will GET a resource from the server, update some values, and PUT it back on the server. PUT is idempotent. If the client sends the same PUT request to the server, the value of the resource should remain the same for each subsequent request.

Response codes used for a PUT:
200 OK
– returns the updated data from the PUT request

204 No Content
– no data is returned but the client knows the PUT was successful.

PATCH:

PATCH is similar to PUT, it is used to update a resource on the server. However, the difference being is that PATCH only updates a subset of a resources data. This can be useful when modifying a large resource. The client and server do not have to send the full object back and forth. PATCH is also useful if multiple users may be updating the same resource. You are less likely to get conflicts if each user is updating subsets of a resource instead of the entire resource.

Response codes used for a PATCH:
200 OK
– returns the updated data from the PATCH request

204 No Content
– no data is returned but the client knows the PATCH was successful.

DELETE:

A DELETE is request is used to remove a resource from the server. The server does not necessarily have to delete the resource, but as far as the client the concerned, they should not see the resource anymore. DELETE is idempotent.

Response codes for a DELETE:
200 OK
– returns some information on the delete

202 Accepted
– accepted the request but will delete the resource later

204 No Content
– the resource is deleted, no need to for a response body.

POST:

A POST is used to insert a new resource on the server. It is not safe or idempotent. If you POST the same request 5 times, you will create 5 resources on the server.

Response codes for a POST:
201 Created
– the resource has been successfully created

202 Accepted
– the server has accepted the POST and will create the resource later

Overloaded POST:
The definition of a POST is extremely vague. In theory, a POST can be used instead of any of the above HTTP methods. However, it should only be used when none of the other methods are applicable. An example is querying for a report. The client may be able to refine the report using numerous search parameters, e.g. start date, end date, user, location, etc. It may be very difficult to accommodate all these criteria in a GET request. In which case, the body of a POST would be much more applicable.

Error Handling:

Errors will always occur. The following are the more common error status codes used to inform the user of what went wrong:
401 Not Authorized
– the user is not authenticated to use the resources.

403 Forbidden
– the user has been authenticated, but is not allowed access the requested resource.

404 Not Found
– Can be used when the requested resource does not exist.

500 Internal Server Error
– The server actually failed to process the request. Could be due to validation failures, or corrupt data. Some prompt should be given to the user as to what went wrong.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.