A particularly popular form of stateless server designs are web APIs that use the REST architectural style, also called REST APIs or RESTful Web APIs.

1 REST

REST officially an abbreviation for representational state transfer, though that longer term is rarely used. REST includes 5 properties:

Client/Server – clients are distinct from servers, interacting though a defined interface or API.
Stateless – servers do not store per-client data.
Cache – each response from the server indicates how long it may be cached.
Uniform interface – the various request and response formats use as similar format to one another as possible.
Layered system – the server is designed to be able to split into many separate computers, with clients unable to tell which computer responded or even if there are several of them.

2 RESTful Web API

In general, RESTful web APIs have the following properties:

Clients send HTTP requests; servers reply.
The HTTP request method describes if/how the request changes server state. The two most common methods used are
- GET does not change server state
- POST changes existing server state
Sometimes PUT is used to create new server state and DELETE to remove existing server state, but sometimes they are both handled using POST instead. Other HTTP request methods are relatively rarely used in web APIs.
The HTTP request path identifies what resource you are accessing.
The HTTP request body (which is not used by GET requests) describes specific changes to be implemented.
HTTP headers may be used to pick one of several equivalent response formats, but should not be used to change the meaning of the request.
All request bodies within a single API use the same format; often JSON or XML, but sometimes the simpler but less flexible application/x-www-form-urlencoded and multipart/form-data formats used by HTML forms and query strings.
All response bodies that provide structured data structure it the same way, often JSON or XML.

3 More on State

A key idea of REST is that programs are stateless, but that does not mean they lack any state. Even databases, which are apps whose sole purpose is to manipulate state, can be exposed through a REST API. To understand what we mean by stateless in a REST sense, let’s consider a few kinds of state¹¹ These are not universal terms, just distinctions that I hope will be helpful in explaining how people talk about REST:

Durable, core, or user-independent state.
Temporary informative state.
User-specific fundamental state.
User-specific navigational state.

Consider an IDE like VS Code.

The bytes the files you are editing are durable, core, user-independent state.
That bytes 10–13 of a given file are a keyword and should be shown in dark blue is temporary informative state.
That the debugger is running and has a break point on line 24 is user-specific fundamental state.
That the window is set up with the debugger pane covering a particular set of pixels is a user-specific navigational state.

Consider an course registration system like Banner.

What courses are in what rooms with what students enrolled in each is durable, core, user-independent state.
That a given course is full is temporary informative state.
That you are logged in as an undergraduate student is user-specific fundamental state.
That you’re currently viewing the list of Spring 2025 CS courses is user-specific navigational state.

The main stateless aspect of REST is that a RESTful service

Does not have user-specific navigational state at all.
Embodies user-specific fundamental state in some kind of token or value passed in by the user with each request, not in any kind of memory about what messages came over this TCP/IP connection in the past.

Terminals are not RESTful. If I send a terminal the command ls, what it will send back is dependent on my history of commands with this terminal connection. If I send it cd .., and then send it ls again I’ll get a different result despite not having changed any durable state.

If you send cd .. to my computer, nothing about my experience will change²² If you send it rm my experience will change, but that’s because rm changes durable user-independent state, unlike cd.. If I open a dozen terminals, the cd commands I send to one do not impact the others. Each terminal session has its own user navigational state that the others cannot impact.

Our course file upload system is RESTful. To upload a file you send a single HTTP request³³ Typically you don’t send this manually; upload.php handles constructing this HTTP request for you. with the following parts:

The path ends ?f= followed by a string consisting of a student NetID like luthert, an MP identifier like mp7, and a file name like chunkserver.py, separated by slashes.
One of the following:
- An HTTP header Authorization: with a value that is an encrypted version of a netid and password.
- An HTTP header Cookie: with a value that encodes a dict, part of the contents of which is a random session ID.
A body that is the bytes of your file.

There’s no navigational state needed by the server: the full information about who you are and what MP you are uploading for is included in your request. There is some user state, in the form of a tool for verifying username/password pairs and a list of random session IDs with what user each maps to, but that state is passed in with each new request.

If someone else could figure out what HTTP headers you are using, they could act on your behalf. That’s part of why we use HTTPS instead of plain HTTP for that page: HTTPS encrypts the entire HTTP, making it prohibitively difficulty to read the headers even if you are part of the chain of computers that deliver the message’s HTTP packets.

Our course file upload webpage is not RESTful.

Although it uses the RESTful upload system, it also has user navigational state: whether the file upload dialog is visible or not, what files you’ve chosen to upload, whether the files have been sent to the server, whether the server has responded: these are all stored by the webpage and used to update the display and make interacting with the back-end upload service more user-friendly.