REST on Yunier's Wiki

Markup Your Web API Documents

Thu, 31 Mar 2022 00:00:00 +0000

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.

Faster Web API Pagination

Thu, 17 Feb 2022 00:00:00 +0000

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.

JSON:API - Pagination Links

Tue, 25 Jan 2022 00:00:00 +0000

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.

{
  "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 In A Web API

Wed, 17 Nov 2021 00:00:00 +0000

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.

Sort Functions Are Non-Deterministic

Sat, 13 Nov 2021 00:00:00 +0000

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.

A Practical Web API Validation Strategy

Wed, 13 Oct 2021 00:00:00 +0000

In my last post I wrote about how you can leverage JSON Schema to do Web API validation. The main benefit is that the API can expose the schema as an API resource, clients of the API can consume the schema and execute it on their end against any data. The benefit of doing API validation like this is that the client does not need to duplicate any validation logic, they only need to execute the schema. In this post, I would like to explore API validation in .NET, using the library FluentValidation and exposing validation errors using Problem Details.

A Better Web API Validation Strategy

Sat, 09 Oct 2021 00:00:00 +0000

As an API developer, you will eventually need to determine how to handle data validation.

The .NET ecosystem offers a few options, the first option, validation attributes, can be used to annotate how a model should be validated. Validation attributes are great, they don’t require any external dependencies, you can specify error messages, create your own custom validator, validate against many data types.

For example, take the following Movie class, notice how the properties have been annotated with validation rules.

JSON:API - Creating New Resources

Sun, 08 Aug 2021 00:00:00 +0000

So far in my JSON:API series I’ve covered the home resource, adding your own resource, adding an exception handling middleware and how to expose relationship between resources. For the today’s post, I would like to cover creating resources. I will update the chinook project by allowing POST request on the customers collections to add new customers.

To get started, the customer controller needs to have a method that will accept the incoming POST request. I’ve decided to call the method CreateCustomerResource, the method will accept a JSON:API document from the request body. The full method signature is defined below.

Problem Details for HTTP APIs

Tue, 11 May 2021 00:00:00 +0000

One of the many benefits of working with JSON:API and GraphQL is having a standardize way to communicate failures to a client. If you are not working with a spec like JSON:API or GraphQL, then you are in the hands of the developer that built the API and every developers implements error handling differently.

Almost every HTTP API that I've consumed implements errors differently. Can we just agree to use Problem Details and be done with it?

JSON:API - Exposing The Customer Resource

Fri, 30 Oct 2020 00:00:00 +0000

This will be my third blog post on JSON:API in .NET Core.

I plant to add Customer as an API resource, but before we get too deep on the code, I would like to review the Chinook database project. To do that I’m going to import Chinook.db into DB Browser for SQLite to see all available entities.

As you can see we have quite a few entities, for this blog post I will concentrate on the customers entity. To accomplish adding customers as an API resource I will need to create a new service model that represents the customers entity in both JsonApiFramework and EF Core. I will scaffold the SQLite database using EF Core’s reverse engineering capabilities.

JSON:API - Exception Handling Middleware

Mon, 19 Oct 2020 00:00:00 +0000

On my second post on JSON:API in .NET Core I wanted to create an exception handling middleware. This middleware would be responsible for catching all exceptions and for generating a JSON:API Errors Documents.

I’ll start by adding a middleware folder on the Chinook.Web project, for now it will only have the exception handling middleware, but, eventually it will have additional middleware.

Folder has been added, now I will add the middleware class to the project in here.

JSON:API - Creating The Home Resource

Mon, 14 Sep 2020 00:00:00 +0000

This post will be my first entry into a multi-part series of post showing how I’ve built RESTful APIs using the JSON:API specification on .NET Core.

I will start by creating a new .NET Core Web Api project, I am going to call this project Chinook, after the sqlite database that I will use for this project. Whenever I create a .NET Core project I like to follow the project structure outlined by Steve Smith in his Clean Architecture repository.