This week I have chosen to deepen my understanding of REST API. The article, “RESTful API Design Tips from Experience” by Peter Boyer, goes over good RESTful design practices. The article covers many topics, including some I do not have experience with but are still useful for a greater understanding overall.
The article proposes that the API should state its version
in the URLs. The author suggests adding a prefix to all URLs to specify API
version. This makes the eventuality of version updates easier to handle.
A simple tip mentioned in the article is the use of plurals.
When designing endpoints, plurals should be used instead of the singular form.
This is to avoid possible misunderstandings of what the endpoint is used for.
Example: /orders/customers VS /order/customer
Another tip in the article is to use nesting for
relationship filtering. From what I understand, it is better to have multiple
path variables for filtering than the use of query strings. The example in the
article is very clear on the tip. Following this advice will make your
endpoints easier to read.
The author advises to keep your API as flat as possible. He
suggests that creating and fetching data should have a longer resource path
than updating and deleting data. I do not really understand why this is the
case. My best guess is the shorter path reduces unnecessary processes.
The next tip I found interesting was the important, if not
obvious, idea for pagination of results. When working with larger databases, requests
can have thousands of results. Since it would be impossible to display all the
data, it makes sense to partition the results into pages and return one page at
a time. Pagination can also significantly reduce the expense of a request.
The last tip I will mention from the article is the usage of
status codes. HTTP status codes should
be used consistently and properly. This means the status should use the proper
code and provide additional details when necessary: an error code with a
message of why the error occurred.
Overall, I found Boyer’s article to be very informative. I
only mentioned a few of the topics raised in his article but all the topics are
interesting and useful. Reading through this article gave me a better
understanding of the nuances of RESTful API design and has helped me comprehend
my current coursework (CS343) better. I suggest to anybody that is new to REST
to read this article.