REST API Specification

Connection between two systems would happen based on REST API. The API developed on one system would be accessed through another system to pull or push the data. This blog specifies a way the API is to be developed.

Request format

API would be called as a standard HTTP request. Below are the examples of GET, POST and DELETE requests that can be made to an API.


GET /api/v1/entity/parameter

POST /api/v1/entity

{
    "param1": "value1",
    "param2": "value2",
    // ...
}

DELETE /api/v1/entity/parameter


HTTP Basic Authentication can be implemented with username and password Base64 encoded and inserted in the header of API requests. These encoded credentials would be decoded and verified for the authenticity of the request made.

All API Requests can be logged with the URL and the request json data to a log file, as per “Common Log Format”
IP DATETIME HTTP_METHOD URL REQUEST_JSON_DATA

Response Format

Variable names are snake_cased

Successful request:

{
    "status": "success",
    "data": {
        /* Application-specific data would go here. */
    },
    "messages": [{}] /* Or optional success message */
    "links" : [
        {
            "href": "http://example.org/resource-path"
        }
    ]
}

Failed request:

{
    "status": "error",
    "data": null, /* or optional error payload */
    "messages": [{"Error xyz has occurred"}]
}

Below are the HTTP codes sent back in response for the HTTP methods used.

GET
– 200 Ok

POST
– 201 Created

DELETE
– 204 No Content

Errors
– 400 Bad Request
– 401 Unauthorized
– 403 Forbidden
– 404 Not Found
– 405 Method not allowed
– 422 Unprocessable Entity
– 500 Internal server error