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

What others say about us

quotes icon

"iSEEit has been closely working with Habilelabs team ever since our company needed to step up development efforts. Being a rapidly evolving software company, we have come across a multitude of challenges over time but Habilelabs has proactively solved issues impacting the business and handled the continuous releases of the applications without downtime. We are very satisfied and happy to have found Habilelabs as our offshore development partner as they have developed a good understanding of our own vision and work flows."

Rizan Flenner

"Amazing and skilled team we been learning from each other for quite some time, and still working together.
Always available and ready to make great results, or to improve unexpected problems."

Daniel White

https://www.siquo.com/

"I am very pleased with the work Habilelabs provides. Every time we have worked, projects were delivered on time. They provide great support and I would totally recommend Habilelabs to anyone that wants to get a project done on time and professionally."

Xenophon Kanarios

http://tableluv.gr/

"Habilelabs is an excellent and affordable programming team that delivers fast results."

Paiusa

Stephen Blaney

http://www.paiusa.com/

"Good mindset, good technical competence and skills, always fix problems when needed."

Arash Fard-Rahmani

"We have been extremely satisfied with the project that has been delivered by Habilelabs. They are very professional with great commitments. Quality of communication and problem solving skills were perfect."

Safak Korkut

"Very much satisfied the work. Team quickly understood the requirements and completed work on time. Would definitely recommend him. We will like to hire them again."

Stanislav M.

"Habilelabs is the definition of professional and friendly. They knew exactly what they are doing and never shy to share their knowledge. We will definitely consider hiring them for future projects! Great Work!."

Eben B.

"Great work, will hire team Habilelabs again. I appreciate the extra effort. Excellent work as always."

Saasmath

"Very fast and professional Team. They knows exactly what needs to be developed to achieve the project goal. We will hire them again"

Mediaroot

"Very good work, Little expencive for us but prefere to work with them because I'm sure the work will be done 100%"

ProwebMedia

"Team habilelabs is a pleasure to work with and we will work with them again. They are professional, easy to communicate with, and completes tasks on time and on budget."

"Really impressed with the high quality work and professionalism!"

Vaibhav Samadhiya

"We worked Habilelabs team and they are very professional, motivated and experienced developer. I would love to work with them in the future again!"

Mahdishahadat

"We had a great collaboration with Habilelabs. They are very communicative, extremely competent and responsive. We are looking forward to continuing our collaboration with Habilelabs. I recommend them with full confidence."

Safkutkorfak

"I'm very impressed with work quality. Habilelabs shows outstanding performance and knowledge in area needed for our project. I'm fully satisfied with Habilelabs's service. Will look for more opportunities to work with them"

AdramMedia

"Team habilelabs are truly great developers to work with, and ensure that the work is completed to the highest of standards. Real pleasure to work with would highly recommend for Node.js / React.js work."

Liamsm

"Habilelabs is a fabulous company. Excellent in quality and always available for communication. We hired Habilelabs team for doing the frontend of my application and they gave me some good tips about backend APIs as well, which tells a lot about their overall expertise. Really appreciate their sincerity, timely delivery and professionalism. Will definitely hire them again in future."

Atul Shrivastava

"very good very profasional, They did good job on time +++"

Moshe Levy

"Love the Company Habilelabs . Knew thier stuff and really came through for me."

Zehash

"5 stars work, very good communication, timely delivery."

Anthony Hu

"iSEEit has been closely working with Habilelabs team ever since our company needed to step up development efforts. Being a rapidly evolving software company, we have come across a multitude of challenges over time but Habilelabs has proactively solved issues impacting the business and handled the continuous releases of the applications without downtime. We are very satisfied and happy to have found Habilelabs as our offshore development partner as they have developed a good understanding of our own vision and work flows."

iSEEit

Rizan Flenner

"Amazing and skilled team we been learning from each other for quite some time, and still working together.
Always available and ready to make great results, or to improve unexpected problems."

Siquo

Daniel White

https://www.siquo.com/

"I am very pleased with the work Habilelabs provides. Every time we have worked, projects were delivered on time. They provide great support and I would totally recommend Habilelabs to anyone that wants to get a project done on time and professionally."

Tableluv

Xenophon Kanarios

http://tableluv.gr/

"Habilelabs is an excellent and affordable programming team that delivers fast results."

Paiusa

Stephen Blaney

http://www.paiusa.com/

"Good mindset, good technical competence and skills, always fix problems when needed."

Denthub

Arash Fard-Rahmani

"We have been extremely satisfied with the project that has been delivered by Habilelabs. They are very professional with great commitments. Quality of communication and problem solving skills were perfect."

Safak Korkut

"Very much satisfied the work. Team quickly understood the requirements and completed work on time. Would definitely recommend him. We will like to hire them again"

Stanislav M.

"Habilelabs is the definition of professional and friendly. They knew exactly what they are doing and never shy to share their knowledge. We will definitely consider hiring them for future projects! Great Work!"

Eben B.

"Great work, will hire team Habilelabs again. I appreciate the extra effort. Excellent work as always."

Saasmath

"Very fast and professional Team. They knows exactly what needs to be developed to achieve the project goal. We will hire them again"

Mediaroot

"Very good work, Little expencive for us but prefere to work with them because I'm sure the work will be done 100%"

ProwebMedia

"Team habilelabs is a pleasure to work with and we will work with them again. They are professional, easy to communicate with, and completes tasks on time and on budget."

KCRW

"Really impressed with the high quality work and professionalism!"

Vaibhav Samadhiya

"We worked Habilelabs team and they are very professional, motivated and experienced developer. I would love to work with them in the future again!"

Mahdishahadat

"We had a great collaboration with Habilelabs. They are very communicative, extremely competent and responsive. We are looking forward to continuing our collaboration with Habilelabs. I recommend them with full confidence."

Safkutkorfak

"I'm very impressed with work quality. Habilelabs shows outstanding performance and knowledge in area needed for our project. I'm fully satisfied with Habilelabs's service. Will look for more opportunities to work with them"

AdramMedia

"Team habilelabs are truly great developers to work with, and ensure that the work is completed to the highest of standards. Real pleasure to work with would highly recommend for Node.js / React.js work."

Liamsm

"Habilelabs is a fabulous company. Excellent in quality and always available for communication. We hired Habilelabs team for doing the frontend of my application and they gave me some good tips about backend APIs as well, which tells a lot about their overall expertise. Really appreciate their sincerity, timely delivery and professionalism. Will definitely hire them again in future."

Atul Shrivastava

"very good very profasional, They did good job on time +++"

Moshe Levy

"Love the Company Habilelabs . Knew thier stuff and really came through for me."

Zehash

"5 stars work, very good communication, timely delivery."

Anthony Hu