Poorly designed API may be cause of security issues and unsafe code. A robust and strong design is a key factor for API success. You should know these 4 Basic Rest API Design Guidelines. https://goo.gl/QaxpSA

1. HABILELABS PVT. LTD.
YOUR INTEREST OUR INTELLIGENCE

2. Habilelabs REST API Guidelines
Shankar Morwal
CTO and co-founder

3. CONTENTS
1. Naming convention
2. Error Handling
3. Versioning
4. Partial Request and pagination
5. Tips

4. 1. API NAMING CONVENTION

5. 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.

6. Collection GET POST Update Delete
/projects List all projects Create a
project
Bulk update
projects
Delete all
project
/projects/:id List one project Error Update a
project if exist
else a error
Delete a
project.
GOOD API NAMES EXAMPLES

7. BAD NAMES(VERBS) EXAMPLES
/getAllProjects
/deleteAllProjects
/deleteProject
/createProject
/updateProject
/filterProject
/proj (short name)

8. SIMPLE ASSOCIATIONS USING GOOD NAMES
• 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

9. 2. ERROR HANDLING IN APIS

10. 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.

11. MAKE RETURNED MESSAGES AS VERBOSE AS POSSIBLE.
EXAMPLE : UNAUTHORIZED REQUEST FOR DIFFERENT
COMPANIES

12. CONFUSED ??
WHAT HABILELABS USE?

13. 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)

14. VERSIONING

15. 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

16. RECOMMENDED FOR HABILELABS
• We will use version number programmatically.
• Use /version/resource
• Examples
/v1/projects
/v1/projects/:id
/v2/user/:id/projects

17. PAGINATION AND PARTIAL REQUEST

18. PAGINATION AND PARTIAL REQUEST
• What others do ?

19. WHAT WE WILL 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

20. 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

21. Questions ?
For any questions drop me line at Shankar@habilelabs.io