RESTful API Standards

Below are the common RESTful API standards that we should follow when designing our API's

Keep your base URL simple and intuitive

 /dogs     /dogs/1234

Keep verbs out of your base URLs

Never use /getDogs or /createDogs

Use HTTP verbs to operate on the collections and elements

POST, GET, PUT, DELETE is CRUD (Create-Read-Update-Delete)

Use Plural nouns

/dogs   /deals    /quotes

Concrete names are better than abstract

Instead of /items be more specific like /blogs  /videos

Number of resources - preferably between 12 to 24

Simplify the Relationship and Association between Resources

GET /owners/5678/dogs

POST /owners/5678/dogs

Keep complexity behind the ‘?’

GET /dogs?color=red&state=running&location=park

Have a good error design

                Aligning errors with HTTP status codes

                200 - OK

                400 - Bad Request from client

                500 - Internal Server Error

                304 - Not Modified

                404 – Not Found

                401 - Unauthorized

                403 - Forbidden

                Provide a more granular error message

                {"status" : "401", "message":"Authentication Required","code": 20003}

Versioning is mandatory

Always use v and never have minor version like v1.0. Ideal is v1, v2

Have version all the way to the left (highest scope): /v1/dogs

Maintain at least one version back

Follow proper cycle for deprecating and retiring the API

Response content type, OAuth etc must go into the header

information which doesn't change the logic for each response goes into the header

Extra optional fields must be requested in a comma-delimited list

/dogs?fields=name,color,location 

Pagination is a must for resource API's

Use limit and offset. 

/dogs?limit=25&offset=50

default pagination is limit=10 with offset=0

For Non-Resource API's: Use verbs not nouns

/convert?from=EUR&to=CNY&amount=100

/translate?from=EN&to=FR&text=Hello

Request format - support multiple if possible

Default should be JSON, but support XML if possible

Use the pure RESTful way with the header, Accept: application/json

Use standard Java/Javascript naming convention for attributes

example: createdAt, firstName

Search within a resource: use ?q=

/owners/5678/dogs?q=fluffy+fur

Have all API's in single store and under one domain

api.mycompany.com

Option to Supress error codes

Always sent HTTP 200, even in case of errors.

&suppress_response_codes=true

Authentication : Use OAuth 2.0

In addition to the atomic API, provide composite API's as well if required - if there is a need

This will avoid applications making multiple calls per screen.

Complement the API with code libraries and a software development kit (SDK)

Note: These are not the only standards and there may be variations. These are the standards which are followed my many and works for them.