We face design issues when we start working on API, poorly designed API may be the 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.
Let’s discuss on basic API design guidelines for creating restful API.
4 Basic Restful API design guidelines are:
1. Naming convention
2. Error Handling and status codes
4. Pagination and Partial request
Let’ discuss on each descriptively.
1. Naming convention:
Nouns are good and verbs are bad for using as naming.
Check out some point for naming:
1. Keep your URL simple and intuitive.
2. Keep Verbs out of your base URLs.
3. Use HTTP verbs like GET, POST, UPDATE, DELETE to work on the collections.
4. Plural names are better than singular names.
5. Some companies use singular but we use the plural.
6. Use concrete names then using short names.
Good API Names:
Bad API Names are verbs:
• Use name convention as /resource/identifier/resource
List all user projects.
Good URL is: user/:id/projects
Bad URL is: /listAllUserProjects
• If associations are complex then sweep complexity behind the ‘?’.
2. Error Handling and status codes:
Let’s check out some 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.
Make returned Messages as verbose as possible.
For Example Unauthorized Request for different companies
Recommended Status Codes are:
• 200 Ok (All went well)
• 400 bad requests (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)
3. Tips for versioning:
• Versioning is one of the most important considerations when designing your Web API.
• Never release an API without using version numbers
• We will use version number programmatically.
• Use /version/resource
4. Pagination and Partial request:
What famous platforms do?
What you should use:
We recommend using Facebook style
Limit: number of projects
Offset: Skip these records
Offset = 0
Limit = 10
Other important Points are:
• Never use get a request to delete a resource.
• In Json response user camelCase in response
• Use partial response syntax.
• Consolidate API requests in one subdomain
For the best practice of API design use standard parameters [latest Naming convention, standard status codes use, correct use of Versioning and correct Pagination].
If you have any query about rest API guidelines, you can ask us in the comment box.
Hope you find this post helpful, so don’t forget to share with friends. (y)