Original Blog: https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/
For this post, I’ve decided to write about what qualities a REST API platform ought to have in order for it to best serve the clients that depend on it. I’ve chosen this topic since it relates to what I’m currently studying in my software and design class.
As of today, REST API platforms are among the most widely used kinds of web interfaces. This is largely because of the versatility they offer in what can communicate with the API. Because of this, some key characteristics and qualities have been noted as essential for most, if not all, REST API platforms to ensure no problems are encountered in using the API. In the blog, “Best Practices for API Design”, by John Au-Yeung, the author details some practices he feels are the most necessary.
The first listed quality is the JSON compatibility, which includes being able to receive requests in JSON and being able to respond in JSON. The main reason for this quality being essential are the fact that most networked technologies either do or can use it with minor adjustments, compared to other frameworks, like XML, which would require the transforming of data so that it could be used. This would be very cumbersome for both the client and the maintainers of the API, and is less preferable than just using an already widely used framework like JSON.
The second listed quality is to make sure the endpoint paths of the API include only nouns describing what an http method acting on that endpoint would affect. For example, a path for using the GET method on a collection of articles would just be called GET /articles/ as opposed to GET /retrievearticles/. Since the http method will always add a verb to the path name, extra verbs that just reiterate what the method does can clutter the syntax of the endpoints. While this quality is maintained, endpoints and their functions are clear throughout the whole API.
The third and final quality mentioned by the author that I’ll include in this post is use of logical endpoint nesting when making paths for related endpoints. This quality says that if there is related or grouped data that can be accessed, structure the paths so that it’s clear that the information is related. The example the author gave was when designing a path to access comments on a specific article, the path should resemble /articles/articles:id/comments. With this structure, it’s clear to the user where the information contained in comments in coming from, and how that information interacts with articles and a specific articles id. This quality is important because it minimizes the amount of possible confusion a user may experience when accessing child resources.
In summary, of the qualities the author chose to emphasize, the ones that stood out to me the most were the logical nesting of paths and the compatibility with JSON. The logical path nesting seems like it could also prevent the problem of users suggesting errors in the API itself, when in reality they’re just confused by the unclear path structure, and JSON compatibility just seems too convenient to not have, and way too cumbersome to operate without, especially if your API is seeing use on a large scale.
From the blog My first blog by Michael and used with permission of the author. All other rights reserved by the author.
