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 basic API design guidelines for creating a restful API-
4 Basic Restful API Design Guidelines
1. Naming convention
2. Error Handling and status codes
4. Pagination and Partial request
Let’ discuss each one 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 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 uses 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 the Login page.)
• 403 Forbidden/ Access denied (logged user does not have access to this resource)
• 500 Internal server error (something went wrong on the 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 do the 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, use 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 queries about the rest API guidelines, you can ask us in the comment box.
Hope you find this post helpful, so don’t forget to share it with friends.