Rest API Guidelines by HabileLabs
Download as PPTX, PDF2 likes157 views
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
More Related Content
What's hot (20)
Similar to Rest API Guidelines by HabileLabs (20)
More from HabileLabs (9)
Recently uploaded (20)
Rest API Guidelines by HabileLabs
- 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 [email protected]