APIs play an integral role in the development of modern-day applications. Whether you are writing your API or integrating someone else’s, it is crucial to understand their functioning. There are many APIs, but the most common types are REST APIs that operate using HTTP and HTTPS. I chose to write about REST APIs because we will be working with them in this class. They are essential to understand for most development projects. The blog post “Best practices for REST API design” discusses the basics of a REST API, how they work, and development practices. The post also provides code examples using NodeJS with the ExpressJS library showing how the concept of a REST API is implemented.

According to the article, a REST API follows a set of standard design principles that allow users to quickly be able to work with the API. For example, a REST API should include method endpoints such as /GET /POST /PUT and /DELETE. These endpoints are used to send and receive data between the server and the client. The difference between the endpoints is the operations they perform. Sending a request to a GET endpoint will send the client data, a POST request will add data, and a DELETE request will remove data.

Although there are a set of rules a REST API must follow, there are many best practices left up to the developer that they should follow. For example, a REST API should send and receive data in JSON. JSON makes working with data simpler because it is in an easily transferable and structured format. The API should also run over HTTPS rather than HTTP to add an extra level of security between communication.

A REST API closely resembles the structure of a URL where each method is separated by a forward slash. To pass a parameter, a question mark is used followed by the variable name equal to a value. In order to be readable, the developer must name and structure the API paths wisely, based on the function an endpoint is responsible for. For example, a GET request to find a user by ID could look something like /user/findOne?id=120. In this example, the findOne method is prefaced by /user/, and we know the user id we are finding is 120. If the API replaced the word user for record, then the developer using the API would not know what type of data to receive in the request.

Finally, a REST API should be versioned, meaning the highest level path of the URL structure should be the API’s version number. Using the find user example, a versioned API would read /v1/user/findOne?id=120. If we made a change to our API, we could modify that in the v2 API without breaking the code written using the v1 API.

I will definitely use these tips while developing a REST API in the future. One of the most important guidelines I learned was to always send and receive data in JSON. In the past, I have made a REST endpoint return a single value such as a number. Without any context, the data from the API would be hard to understand. If the values were named in JSON then it would be easier to work with and manipulate.

Reference blog resource: stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design

From the blog CS@Worcester – Jared's Development Blog by Jared Moore and used with permission of the author. All other rights reserved by the author.