In this series of articles, I’d like to address some of the difficulties that occur during the design of REST APIs. This article is about difficulties with designing a resource that behaves differently under different circumstances. We call these circumstances its state. A REST API should present the resource state in a fundamentally different way than what most developers would already be familiar with. Because of this, developers will often present the resource state in a way that doesn’t adhere to the REST constraints. This in turn means we don’t get the benefits intended by those constraints.

In this series of articles, I’d like to address some of the difficulties that occur during the design of REST APIs. This article is about difficulties with determining and understanding the domain. In the previous article, I discussed the difficulties with resources, which you should express in terms of the domain. This requires you to determine what domain is relevant to your API and understand it fairly well. This makes the domain an important part of API design.

In this series of articles I’d like to address some of the difficulties that occur during the design of REST APIs. This first article is about difficulties with defining resources. Resources are the key abstraction of information in REST which makes them an important part of API design.