DEV Community

loading...
Cover image for 8 Best Practices for REST API Design

8 Best Practices for REST API Design

mohit199thd profile image Mohit Originally published at javascript.plainenglish.io ・2 min read

1. Automate Caching

Repeated request and responding to those request consumes resources and this becomes a sign of flawed design. To solve this problem you must store data fetched from the API on the server and serve later from there.
However, there are times when the data becomes outdated and needs to be updated, in this case, we have some industry caching solutions (Redis and Amazon ElasticCache) that can cache data even after making changes.

2. API Documentation

Always provide clear and concise documentation is necessary for any API, it becomes harder to use that API later without good documentation. So make sure that your API has good documentation using simple languages with updates and new releases.
Your API Documentation should include the following:

Simple and easy to read language.
Implementation of API in different programming languages.

3. Don't Return Plain Text

It is not necessary to go above JSON in REST architecture, as most REST APIs use JSON as a data format. But there are times when returning a body that contains a JSON-formated string isn't enough.

Such as you can specify the Content-Type header set to the value application/json.

4. 401 VS 403

Both the status codes have different meanings and it is very easy to get confused whether it related to authentication or authorization. In order to resolve issues faster, you need to know the difference.
If the user hasn't provided authentication details or they were invalid, then it is 401 Unauthorized.
And if the user successfully authenticated but didn't provide the permissions to access the resource, then it is 403 Forbidden.

Read More at: https://javascript.plainenglish.io/8-best-practices-for-rest-api-design-3fd1b837b283

Discussion (10)

Collapse
greenroommate profile image
Haris Secic

Couple of things to add hope you don't mind:

Chaching can be done in many different ways for REST before going to catching requests server side. Look at ETag, expiry time, or others. Let the client do some work as well.

404 is used as well instead od 403 to properly protect resources. Why would a use know that a resource exists if they don't have access to it? It's implicit leakage of information or better yet meta-data as in "resource exists under given criteria like under given ID". And one could argue it breaks no REST rules as server cannot find any resource for given criteria that relates to that user.

Collapse
rafarochas91 profile image
Rafael Rocha

Very good points, for example when it comes to auth you don't want to leak information about what kind of user data exists or doesn't with a 404. That enables to scan what data is there or not as a consumer of the API. Different status codes may be given to the same use cases depending on privacy or auth.
Good catch!

Collapse
aarone4 profile image
Aaron Reese

I agree to the extent that you are leaking metadata but the codes are for context. As a developer hitting your API I need a 403 or 401 to understand whether I have hit a rate-throttle or my token has expired and I need to reauthenticate.

Collapse
greenroommate profile image
Haris Secic

And as a developer of API you use I don't want to give you that info so you get 404. Hehe. I understand your point but just a perspective on why you won't get it sometimes

Thread Thread
aarone4 profile image
Aaron Reese

And I'll just use a competitors company and their API because it's easier to code against
:)

Collapse
lmendev profile image
Luis Mendoza

What do you think about API URI Versioning? v1 v2 v3... πŸ€”

Collapse
tcelestino profile image
Tiago Celestino

It’s my big question.

Collapse
dakujem profile image
Andrej Rypo

Yes, and then v4, I guess.

Collapse
aarone4 profile image
Aaron Reese

It's the least worst option. It really depends on why the API has changed and whether the changes are in the required or response

Collapse
dakujem profile image
Andrej Rypo

Wait... There are only four.

Forem Open with the Forem app