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