In class, we have continued the usage of REST API, and we will only continue to use it. Through homework assignments and class activities, I’ve gotten more comfortable with REST API, but will need to have a good understanding of it as it is a vital part of my capstone project next semester. I found this blog of Stack Overflow that listed some best practices for REST API design that I was previously unaware of or did not have full knowledge of.
Nest Endpoints That Contain Associated Info
If your database has objects that contain other objects, it is a good idea to reflect that in the endpoints. An example from guestInfoBackend would be “/guests/:uuid/assistance/”. This URI is used to access the “assistance” object inside a specific guest. But note that having multi-level nests can get out of hand. A bad example would be having an endpoint that looks like: /articles/:articleId/comments/:commentId/author. It is better to use the URI for the specific user within the JSON response as follows: “author”: “/users/:userId”.
Return HTTP Response Codes Indicating What Kind Of Error Occurred
HTTP response codes help to eliminate confusion when an occurs. Response codes give the API maintainers enough information to understand the problem that has occurred. The blog also showed some other common codes that were not discussed in class:
- 401 Unauthorized – user isn’t not authorized to access a resource; usually returns when the user isn’t authenticated.
- 403 Forbidden – user is authenticated, but not allowed to access a resource.
- 502 Bad Gateway – invalid response from an upstream server.
- 503 Service Unavailable – something unexpected happened on the server side; this could be anything from server overload to some parts of the system failing.
Messages also need to be attached to response codes so that maintainers have enough information to troubleshoot the issue, and that attackers can’t use any of the error content to launch attacks.
Maintain Good Security Practices
The communication between client and server should be private. A good way to secure your REST API is by loading an SSL/TLS certificate onto the server. They are very low cost or even free to use, so it is a no-brainer to strengthen security. It is also a good idea to apply the principle of least privilege. Each user should have role checks or more granular permissions. The admin should not have an issue adding and/or removing permissions and roles from users.
Version APIs
In order to prevent clients from being broken while making changes to the API, different versions of the API should be available. This way, old endpoints can be phased out instead of forcing everyone to switch over to the new version at the same time. This is important for public APIs and is how most apps today handle making changes.
Source
https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/
From the blog CS@Worcester – Blog del William by William Cordor and used with permission of the author. All other rights reserved by the author.







