API is an interface that two systems will use to exchange information. There are different types of API architecture, REST, SOAP, gRPC, WebSocket, GraphQL, and MQTT. Among all of them, REST APIs are the most popular, because of their performance and scalability REST APIs have gained widespread adoption. It has a widespread use case, from building web and Mobile Applications to providing communication between microservices. But it is not all good or not suitable for every situation. Situations like real-time communication are the drawback of REST APIs.

As a CS major or professional, whenever you are trying to learn a new programming language or a new tech, you should always follow best practices. Today, I am going to discuss some best practices and guidelines for REST APIs. I will not cover everything, but it should cover the major parts.


Urls and Endpoints:

Naming Convention: When determining URLs or Endpoints you should name them in a way that explains itself. For example if you have an endpoint that will give vendor names, it should be like this /v1/vendors. You should always use lowercase letters in URLs.

Versioning: Whenever you are setting your endpoints, there should be the version number. For example:
Correct: “https:://example.com/myapi/v1/vendors”

Incorrect: “https:://example.com/myapi/vendors”

Use Unique ID for a single batch of data: Unique IDs are like primary keys in a database table. The format of an ID can be anything, it is totally up to how a developer or architect wants to design it. A lot of beginner devs do an incremental ID for this which is a huge risk for security. You should use UUID because it has a low collision rate.

Methods and Status Code:

The common methods are CRUD operations. It will GET, POST, PUT, DELETE. There are other methods also like PATCH and HEAD, but those are not commonly used.

GET: GET methods should only be used to retrieve resources. 200 status code should be in response. GET methods should not do any updates or new creations. If you want to add filters or parameters, they should be passed as Query Parameters or Path Parameters. You can also use headers. But it should not be passed through the Body.

POST: POST methods should only be used to create resources.  201 status code should be in response. Post methods should not do any retrieves or updates. All the properties should be passed through the BODY. it should not use Query Parameters or headers. Unique ID should not specified. It should be automatically generated. You should only show the status code and the ID in the response.

PUT: PUT methods should be used only to update resources. You should use PUT when you are updating a resource or creating one when you already know the ID. In PUT methods, all properties should be passed on to the body. On the other side, you can use PATCH when you need to update partially. You should not use PUT when you are partially updating a resource.  204 status code should be in the response. 

DELETE: DELETE methods should only be used to delete resources. 204 status codes should be passed in the response. You can always use Soft Delete. You can have isActive data property. When you are deleting you should isActive to false. It is not always where you have to use soft delete, but there will be cases where you have to. 

Status Code: You should always use the Status code properly. 2XX codes should be used for successful requests. 3XX codes should be used for redirection. 4XX codes happen when a client fails to make a valid request. 5XX happens when a server fails to respond to a successful client request.

I cover the 2 major parts of the REST API best practices. Try to follow this when you are developing. These checks seem very beginner-level. But a lot of devs do forget this cause we want to solve problems and we want to do it fast. Stay Focused, Stay consistent.