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. 4 BASIC API DESIGN GUIDELINES

3. 4 BASIC API DESIGN GUIDELINES
1. Naming convention
2. Error Handling and status codes
3. Versioning
4. Pagination and Partial request

4. 1. 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

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

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

9. 2. ERROR HANDLING & STATUS CODE

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

13. 3. VERSIONING

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

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

16. 4. PAGINATION AND PARTIAL REQUEST

17. PAGINATION AND PARTIAL REQUEST
• What others do ?
Read Complete Post Here:

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

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

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

21. THANK YOU
http://www.habilelabs.io/