Skip to main content

What is ReST? (and a bunch of other stuff about API testing)

"ResT" in the context of a software Application Programming Interface (API) stands for "Representational State Transfer". Like many software design patterns, ReST is a pattern, not an implementation. Before we dig deep into ReST though, let us talk about APIs in general.

When we in the QA/test world talk about APIs, we usually mean APIs exposed to users in order to manipulate software systems efficiently from the outside. These are public-facing APIs, as opposed to internal APIs set up at boundaries between disparate subsystems within the application itself. There are any number of public facing API schemes that are not ReST. SOAP is still widely in use. CORBA was a pioneer design in public APIs. AJAX (Asyncronous Javascript And XML) is an API that enables things like sliding maps in a browser. And applications may have their own proprietary public APIs: the Salesforce API is a notable example; while similar to SQL and some other things, the Salesforce API is unlike anything else in the software world.  

A ReST API is typically implemented as json data sent over HTTP. ReST APIs sending XML over HTTP are also feasible. However, not every json-over-HTTP or XML-over-HTTP API is "ReSTful". I once worked with an XML-over-HTTP API whose only method was GET. This is not ReSTful.

The essence of a ReST API is: the client wants the system to be in a particular state. The server will either make the system conform to that state, or else it will tell the client why that is not possible. The "representation" of the "state" is "transferred" from the client to the server. The client says "Be this way" and the server either says "OK" or else it tells the client why that can't happen. This is ReST. (In the case of a GET request, the state of the system is transferred from the server to the client.)

For example, the client may want User X to exist in the system. The client may issue a GET request asking "Does User X exist?" and the server will reply either "no" or may supply information about a User X that exists. If User X does not exist, the client will then issue a POST request with appropriate information to create User X on the system.

The client may want for User X to buy Product A. The client may issue a GET request asking "Does User X own Product A?". The server will reply "no". The client will issue a POST request with the details by which User X purchases Product A.

(I deliberately omit discussion of HTTP PUT and DELETE commands, let us just cover the basics.)

The essence of the ReST design pattern is that it is the client that determines the state of the system. The server merely implements what the client asks, or else explains to the client why this is not possible.

This is the genius of the ReST design pattern: some clever people discovered that the state of the server-side system request could be communicated to the client solely by means of HTTP status codes. So the client will tell the server "Be this way" and the server will reply in only one of several limited ways:

  • 20X: OK it worked
  • 30X: what you're trying to do exists, but it lives somewhere else and you have to ask over there
  • 40X: the server can't do that and it's your fault
  • 50X: the server can't do that and it's my fault

The mechanism of a ReST API is a simple transaction between a web client and a web server. Behind the web server could be literally anything. The web server's job is to translate the client's request into any number of actions on the whole back end system to accomplish what the client is asking. Whether those changes actually occur correctly is the challenge for the API tester. (Hint: those 50X errors are where the bugs are.)

Note that access to the API is a significant tool in the toolbox of the User Interface (UI) tester. Tell the API to set up User X and buy Product A: then check in the UI that User X owns Product A. You are a test wizard.

Bonus story! In 2008 the ideas behind ReST were fairly new and very popular, but not well understood. I had been working with a really well-designed ReST API for some time. I was at a conference and got into a conversation with a developer who was trying to find an answer to the question "How do you make LOGIN ReSTful?" and we butted heads. Authentication is an entirely different problem than setting system state. He never got it. May as well ask "How do you make a grapefruit be a blueberry?" Do not confuse the purpose of a ReST API with APIs dedicated to different purposes.