Linking

Linking is fundamental to scalability and flexibility of the system

MANY to MANY Relationship (example to be added later)

Represent the links separately

e.g. users and groups have many to many relations

Information about users/1 will return,

users/1
users/1/groups/1

users/1/groups/2
groups/1

Dealing with relations

If a relationship can only exist within another resource, RESTful principles provide useful guidance. e.g. A Class consists of a number of sections. These sections can be logically mapped to the /classes endpoint as follows:

• GET /classes/12/sections - Retrieves list of sections for class 12

Limiting which fields are returned by the API

The API consumer does not always need the full representation of a resource. The ability to select and choose returned fields goes a long way in letting the API consumer minimize network traffic and speed up their own usage of the API.

Using a comma-separated list of fields to include in the fields query parameter allows you to restrict what data is returned.  For example, the following request would retrieve just enough information to display a sorted listing of open tickets:

GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

Search and other Algorithms

Use a combination of collection and query parameters to filter out information appropriately.

Efficiency

• Query parameter use ?expand=xyz to expand the xyz resource
• Alternately, return fields=givenName, surname,directory(name)
• Should support parameters offset and limit

you can also add nested partial fields

in the following format

fields?=id,customer(id,name)

in this case, return object will in the following format

[{
    "id":"12",
    "customer":{
      " id": "232",
      "name" :"abc corp"
    }
},
...
]

Request

The API MUST use proper HTTP methods, and operation idempotency* MUST be respected. Below is a list of methods that APIs SHOULD support. Not all resources will support all methods, but all resources using the methods below MUST conform to their usage.

GET /dogs

GET /dogs/10

POST /dogs

PUT /dogs/10

PATCH /dogs/10

DELETE /dogs/10

OPTIONS /dogs

*Idempotence is the idea that a client can make the same call repeatedly while producing the same result. In other words, making multiple identical requests has the same effect as making a single request.

**An operation is considered safe if the operation does not significantly alter the state of the application

Responses need to contain either JSON or XML. Ideally, let consumers provide their preference by specifying an accept header in order of preference.

Response

Success Scenario

• 200 if you want send some additional data in the Response.
• 201 Response to a POST that results in a creation of a resource. Should be combined with a Location header pointing to the location of the new resource.
• 202 Operation deleted has not been committed yet.
• 204 Request successful but no content.
• 304 Not Modified - Used in response to conditional GET calls to reduce bandwidth usage. If used, must set the Date, Content-Location, ETag headers to what they would have been on a regular GET call. There must be no response body.

ERRORS and Exceptions:

Errors should be as descriptive as possible. The following format is recommended

JSON payload

{
  "message": string,
  "developerMessage": string,
  "moreInformation": string,
  "errors": [
    {
      "message": string
    }
  ],
  "code": string
}

Note:

• Either message or message array needs to exist.
• All other elements are optional and if the value is null, the element should be omitted. An element should not be an empty string.
• Use an array of messages to capture multiple validation errors.
• 400  The request is malformed, such as if the body does not parse 
• 401  Unauthenticated. When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
• 403  The request is a legal request but user is unauthorized
• 404  Not Found - When a non-existent resource is requested
• 405  When an HTTP method is being requested that isn't allowed for the authenticated user. 
• 409  Resource Conflict can be possible in complex systems. It can be caused by fulfilling the request. Duplicate entries, deleting root objects when cascade-delete not supported are a couple of examples.
• 410  Gone - Indicates that the resource at this endpoint is no longer available. Useful as a blanket response for old API versions
• 415  Unsupported Media Type - If incorrect content type was provided as part of the request
• 422  Unprocessable Entity - Used for validation errors
• 429  Too Many Requests - When a request is rejected due to rate limiting

HTTP Error Code 

Client error codes

Server Error Codes

• 500 INTERNAL SERVER ERROR – The general catch-all error when the server-side throws an exception
• 501, Not Implemented. The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource
• 503 Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the serve

Business Exceptions

While none of the HTTP response codes match well with a business rule exception, use of the HTTP code 403 indicates that the server is refusing to fulfill the request.  This status code can be used when a business rule won’t allow fulfillment of the request - e.g. Enrollment when a class is full.

Timestamp

Per ISO 8601 guidelines, always use UTC time zone.

Security 

It is recommended to follow all of OWASP’s REST security guidelines and to specifically pay careful attention to:

• Always use SSL. No exceptions
• Keep it stateless as much as possible
• Avoid sequential numbers for the resource ID