Habilelabs-Logo
Blog

4 Basic Rest API Design Guidelines You should know

July 17th, 2017 . 4 minutes read
Blog featured image

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

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 uses 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 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:

Tips for versioning

• Versioning is one of the most important considerations when designing your Web API.
• Never release an API without using version numbers

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:

Pagination and partial request by famous companies

What do the famous platforms do?

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, use 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 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.

Author: morwal89
Share: