Please note that this is a little more technical than my previous articles – sometimes I need to let my inner-geek out.
Simply because RESTful APIs are based on resources and use the HTTP verbs (GET, POST, PUT, DELETE, PATCH), does not mean they should only support CRUD (Create, Read, Update, Delete) operations. RESTful APIs can also be used for performing other actions on
resources.
I was challenged with this recently when explaining the concepts of a layered API architecture (see my
previous article for more information) during a Domain Driven Design workshop. Core APIs, which expose core domains objects, support pure CRUD operations and make full use of the HTTP verbs. These are well within the perceived CRUD definitions of RESTful
services. Process and experience APIs, which orchestrate or compose core APIs to create a defined process, tend to move away from this understanding; and are sometimes a cause for confusion. What HTTP verb should be used for an operation outside of the CRUD
set and how should we graft the URL?
Let’s start with the basics. The naming convention for resources in RESTful APIs should be noun based; we work with “accounts”, “customers”, “products”, etc. The basic CRUD operations we perform on these resources are defined by the HTTP verbs. So, for example:
GET http://www.api.com/customers - gets a list of customers
POST http://www.api.com/customers - creates a new customer based on the representation in the body of the request
PUT http://www.api.com/customers/123 - replaces the customer identified by “123” with the representation in the body of the request
PATCH http://www.api.com/customers/123 - updates the customer identified by “123” with the representation in the body of the request
DELETE http://www.api.com/customers/123 - deletes a customer identified by “123”.
The PUT, PATCH and DELETE HTTP verbs imply very specific Update and Delete actions in the realm of HTTP; they will not work for activity-based APIs. A GET request only consists of the URL to fulfill the HTTP request; you cannot provide content in the request
body (we’ll ignore the use of HTTP Headers for now – they serve a completely different purpose). A POST request allows you to provide content within the request body, so is best placed for an activity-based API.
Now that we’ve identified that the HTTP POST verb is the appropriate choice, how then do we graft the URL to identify what activity (“action”) we want to perform on the resource?
A method driven approach to URL design is often used: http://www.api.com/authenticateCustomer or
http://www.api.com/validatePaymentRequest. However, while this seems to make sense, in my view, it moves away from the resource orientation of RESTful URLs. You may struggle to consider one resource in isolation, but rather have to be aware
of multiple related or interacting resources and actions. This can lead to a plethora of inconsistent URL patterns and approaches – making it difficult for developers to learn how to use your APIs.
Maintaining a resource-based URL representation is surprisingly simple. I use verb-based terms to identify the action I want to perform on the resource in question. The URL is grafted by appending the verb to the resource-based URL. Using the POST method, I
can provide the details required for the activity in the request body.
For example, consider:
POST http://www.api.com/customers/123/authenticate - “authenticate” is the action I want to execute on the customer identified by “123”. The request body contains a representation of the customer required for the authentication.
The important principle to be aware of here is that resources MUST be noun-based (describe the resource) and actions MUST be verb-based (describe the action).
By definition and for clarity, REST (Representational State Transfer) is a software architecture style that defines a set of constraints to be used when creating web services. These constraints include:
- A client-server architecture which supports the separation of concerns principle – allowing components to evolve independently.
- A stateless client-server communication – where each request from the client contains all the data required to service the request. No client context is stored on the server.
- Responses must, implicitly or explicitly, define themselves as cacheable or not to prevent clients from getting stale or inappropriate data in response to further requests.
- A layered system where the client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.
- A uniform interface is fundamental to the design of any RESTful system. It simplifies and decouples the architecture, which enables each part to evolve independently.
Being resource based is inherent in RESTful APIs and the standard set of HTTP verbs tend to imply CRUD operations only; so, I do understand where the misconception comes from.
Craig Hughes
Image sourced from Pexels.com