REST

I’ve been thinking about what it takes to build a good Web API, regardless of the technology (REST vs GraphQL) or philosophy used. One concept that has been stuck on my head is the idea of marking up API documents to provide more context around the data. A Web API document is the response returned by the API itself, you will often see this term used in API specifications like GraphQL, HAL, JSON-LD, and JSON:API. Web API documents can be very simple, for example, imagine working with a Web API that manages users. This API may choose to represent the user resource using the following JSON. ...

A few weeks ago I came across a blog post from Aaron Francis in which he talks about creating efficient pagination using deferred joins. A technique he remembered reading in High Performance MySQL: Proven Strategies for Operating at Scale. The idea is that without deferred joins pagination queries can impact response time. Pagination is done using an OFFSET to skip over a number of records, however, even though the results are skipped, the database must still fetch those records. Meaning we are reading data from the disk and immediately discarding it. This is an inefficient process and is what causes pagination performance to degrade as you paginate over more records. ...

It has been a while since I blogged about JSON:API. In my last post on JSON:API I covered how to create new resources. In today’s post, I want to go over how I expose pagination links. Pagination links allow a client to page through a collection of resources. A shift of control from the client back to the server. Here is an example of a possible JSON:API response that includes pagination links. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "data": [ { // omitted for brevity } ], "links": { "up": "http://example.com/", "self": "http://example.com/articles?page[number]=3&page[size]=1", "first": "http://example.com/articles?page[number]=1&page[size]=1", "prev": "http://example.com/articles?page[number]=2&page[size]=1", "next": "http://example.com/articles?page[number]=4&page[size]=1", "last": "http://example.com/articles?page[number]=13&page[size]=1" } } As you can see, along with the data object, the API responses included a Links object, within the Links object, you can find links for up, self, first, prev, next, and last. These are all relationship name as defined in Link Relations by the Internet Assigned Numbers Authority (IANA). ...

Idempotency, is one of the key features any Web API should have. The idea is that software is unrealiable, the network can fail, the database the API connects to could be offline, the API itself could be performing an intense operation that impacts performance. For all these reasons an API client may resubmit a request, not much of a problem if you are dealing with GET, HEAD, PUT or DELETE, these HTTP methods are idempotent, POST and PATCH on the other hand are not. ...

When building a Web API, RESTful or GraphQL, you may want to expose some functionality that allows a client application to sort data. From my experience, this is often not implemented correctly. Many developers fail to realize that sorting should always be sort plus one. The plus one is a unique value, like a primary key or identifier. The reason for this is that sorting in most databases, like SQL Server, is nondeterministic, meaning the sort function may return different results each time they are called with a specific set of input values even if the database state that they access remains the same. ...