Habilelabs Pvt. Ltd. outlines its REST API guidelines focusing on best practices for naming conventions, error handling, versioning, pagination, and partial requests. Key recommendations include using plural nouns for URLs, adhering to standard HTTP status codes for errors, and implementing versioning in API endpoints. The document emphasizes simplicity and clarity in API design to enhance usability and maintainability.

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