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
Top comments (10)
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.
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!
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.
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
And I'll just use a competitors company and their API because it's easier to code against
:)
What do you think about API URI Versioning? v1 v2 v3... 🤔
It’s my big question.
Yes, and then v4, I guess.
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
Wait... There are only four.