HABILELABS PVT. LTD.

YOUR INTEREST OUR INTELLIGENCE

4 BASIC API DESIGN GUIDELINES
4 BASIC API DESIGN GUIDELINES

1. Naming convention
2. Error Handling and status codes
3. Versioning
4. Pagination and Partial request
1. NAMING CONVENTION
NOUNS ARE GOOD, VERBS ARE BAD.

Keep your URL simple and intuitive.

Keep Verbs out of your base URLs.
Use HTTP verbs like GET, POST, UPDATE, DELETE to work on the collections.
Plural names are better then singular names.
Some companies use singular but we use plural.
Use concrete names then using short names.
GOOD API NAMES

Collection GET POST Update Delete

/projects List all projects Create a Bulk update Delete all

project projects project

/projects/:id List one project Error Update a Delete a

project if exist project.
else a error
BAD NAMES(VERBS)

/getAllProjects
/deleteAllProjects
/deleteProject
/createProject
/updateProject
/filterProject
/proj (short name)
SIMPLIFY ASSOCIATIONS
Use name convention as /resource/identifier/resource
List all user projects
Good URL
user/:id/projects
Bad : /listAllUserProjects

If associations are complex then sweep complexity behind the ? .

Eg. /projects?stage=open&&?value=0,1000
2. ERROR HANDLING & STATUS CODE
ERROR CODE CONVENTIONS
Many companies use different error code conventions.
Use HTTP status codes and try to map them cleanly to relevant standard-based codes. There are over 70
HTTP status codes. However, most developers don't have all 70 memorized. So we do not use them all.
Facebook use only error code 200.
MAKE RETURNED MESSAGES AS VERBOSE AS POSSIBLE.
EXAMPLE : UNAUTHORIZED REQUEST FOR DIFFERENT
COMPANIES
RECOMMENDED STATUS CODES

200 Ok (All went well)

400 bad request (Some required param is missing)
401 Unauthorized ( User not login in. Consumer(Web app, mobile app) of this API should redirect to
Login page.)
403 Forbidden/ Access denied (logged user does not have access to this resource)
500 Internal server error (something went wrong on server)
3. VERSIONING
 TIPS FOR VERSIONING

Versioning is one of the most important considerations when designing your

Web API.
Never release a API without using a version numbers
RECOMMENDED FOR YOU

We will use version number programmatically.

Use /version/resource
Examples
/v1/projects
/v1/projects/:id
/v2/user/:id/projects
4. PAGINATION AND PARTIAL REQUEST
 PAGINATION AND PARTIAL REQUEST

What others do ?

Read Complete Post Here:

WHAT YOU SHOULD USE?

We recommend to use facebook style

/v1/projects?limit=25&offset=50
Limit : number of projects
Offset : Skip these records

Defaults
/v1/projects
Offset = 0
Limit = 10
OTHER IMPORTANT POINTS

Never use get request to delete a Resource.

In Json reponse user camelcase in reponse
Use partial response syntax.
/v1/projects/?fields=name,id,stage
Consolidate API requests in one subdomain
graph.facebook.com
api.facebook.com
CONTACT US

Visit Habilelabs: http://www.habilelabs.io/

Contact us: http://www.habilelabs.io/contact-us/
Like us at facebook: https://www.facebook.com/habilelabs/
 THANK YOU

http://www.habilelabs.io/