Request a Call Back
X
Fields marked with an * are required
4 Basic Rest API Design Guidelines You should know - Habilelabs

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
3. Versioning
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:

good api names

Bad API Names are verbs:

Bad api names

Simplify associations:

• Use name convention as /resource/identifier/resource
List all user projects.
For example:
Good URL is: user/:id/projects
Bad URL is: /listAllUserProjects

• If associations are complex then sweep complexity behind the ‘?’.
Ex. /projects?stage=‘open’&&?value=0,1000

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.

error codes used by other companies

Make returned Messages as verbose as possible.
For Example Unauthorized Request for different companies

Authorized request for other 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
Tips for versioning

Recommended are:
• We will use version number programmatically.
• Use /version/resource
Examples:
/v1/projects
/v1/projects/:id
/v2/user/:id/projects

4. Pagination and Partial request:

What famous platforms do?
Pagination and partial request by famous companies

What you should use:

We recommend using Facebook style
/v1/projects?limit=25&offset=50
Limit: number of projects
Offset: Skip these records

Defaults
/v1/projects
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.
/v1/projects/?fields=name,id,stage
• Consolidate API requests in one subdomain
graph.facebook.com
api.facebook.com

Conclusion:

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)

Shankar is CTO and Senior Software Architect at Habilelabs. He is passionate about JavaScript, Node.js, Angular.js, Meteorjs and cutting-edge front-end technologies. He also enjoys mathematics, he is constantly finding new ways to apply maths theory to web development for improving performance.