REST: resources and HTTP operations

Objectives

By the end of the lesson, you can say what the REST approach means, you can assign resource-based endpoints and HTTP operations to a task, and you can separate REST from "the API returns JSON".

Why does an API need a design approach?

If every API designer invented their own logic (/getKurzus?id=3 in one, /kurzus/lekeres/3 in another), developers would have to learn every service separately. REST (Representational State Transfer) is an architectural approach built on web resources and the proper use of HTTP: the address identifies, the method signals intent, the status code the result. Whoever knows HTTP (chapter 2) is largely at home in a REST-like API. According to MDN, REST is a set of design constraints aiming at efficient, reliable, and scalable distributed systems.

Courses as resources

A resource is an identifiable thing. In Kurzuspont, the collection of courses and a specific course are separate resources: /api/kurzusok is the collection, /api/kurzusok/webprog is one course. The concrete addresses are design decisions; what matters is that identifiers carry a followable meaning.

flowchart LR
    G["/api/kurzusok: collection"] --> K["/api/kurzusok/webprog: one course"]
    K --> R["JSON or another representation"]

The server provides the resource in different representations (for example JSON). The client works with the representation; it does not open a remote database table.

The meaning of the HTTP methods

The methods appear with their meaning from lesson 2.3: GET reads, POST creates or processes, PATCH modifies partially, PUT replaces completely, DELETE deletes. The real responses of the trial API of Kurzuspont (shortened):

Request	Goal	Response
GET /api/kurzusok/webprog	fetch one course	200 OK + JSON
GET /api/kurzusok/nincs	nonexistent course	404 Not Found + {"hiba":{"kod":"nincs_ilyen_kurzus",...}}
POST /api/jelentkezesek {"kurzus":"webprog"}	create an enrolment	201 Created, Location: /api/jelentkezesek/1
POST /api/jelentkezesek {"kurzus":"adatbazisok"}	full course	409 Conflict + {"hiba":{"kod":"betelt",...}}
POST /api/jelentkezesek (non-JSON body)	wrong type	415 Unsupported Media Type
PATCH /api/kurzusok/webprog {"cim":"..."}	modify the title	200 OK + the new state
DELETE /api/kurzusok/adatbazisok	delete a course	204 No Content
DELETE on the same again	already deleted	404 Not Found

The full form of a request and its response:

$ curl -i -X POST http://localhost:8081/api/jelentkezesek \
    -H 'Content-Type: application/json' -d '{"kurzus":"webprog"}'
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /api/jelentkezesek/1

{"id":1,"kurzus":"webprog"}

The 201 indicates that a new resource was created, and the Location header gives its address. For a full course the server answers 409 Conflict: the request is formally correct, but conflicts with the state of the resource (2.4).

The table is one possible contract, not a real university API. Not every user is authorized to create or delete: the method and the authorization are separate questions, just as technical correctness and the fulfilment of business rules are.

Statelessness and consistent errors

One important constraint of REST is stateless client–server communication: every request carries the information needed to interpret it, and the server does not rely on the application-level conversation state of the client's previous request having stayed with it. This does not forbid the server from storing data, and it does not mean that a user could not have a login. The logged-in state is handled with an identifier attached to the requests (chapter 7).

It is also worth giving the errors a consistent error format. In the example above every error has the shape {"hiba":{"kod":...,"uzenet":...}}, so the client receives not just a number but a processable cause: the kod is for the machine, the uzenet for the human. The error response is part of the contract (5.6).

What does not follow from REST?

Another API style can also be justified. If the client wants to choose precise fields from many kinds of connected data, or calls remote operations marked by name, the next lesson presents different approaches.

Worked example: the endpoints of Kurzuspont

Task	Endpoint	Method	Successful response
Course list	/api/kurzusok	GET	200
One course	/api/kurzusok/{id}	GET	200
Enrolment	/api/jelentkezesek	POST	201
Withdrawal	/api/jelentkezesek/{id}	DELETE	204

"One course" and "enrolment" are separate resources: an enrolment has its own identifier, which is why it can be withdrawn separately. If the withdrawal is repeated, DELETE is idempotent (2.3), so the second call is harmless. Repeating the POST, however, can create two enrolments for the same course, unless the server protects against it.

Common misconceptions

Statement	Clarification
"REST = JSON."	JSON is only a possible representation.
"Every POST is a creation."	The contract can assign other processing to it.
"Stateless = the server stores no data."	It is about the conversation state between requests, not the absence of a database.
"Noun URLs make any API REST."	The HTTP semantics and the further constraints matter too.
"A 200 is enough for every response."	The exact status code (201, 204, 404, 409...) gives information to the client.

In brief

• REST builds on resources and the proper use of HTTP: the address identifies, the method signals intent, the status code the result.
• A resource can have several representations (for example JSON).
• It is stateless: the request carries all the necessary information by itself.
• The error format is part of the contract.
• "Returns JSON" and "REST" are not the same.

Review questions

1. What is the difference between the address of a collection and that of a single resource?
2. What does 201 Created mean, and what is the Location header good for?
3. Why is 409 Conflict the response for a full course?
4. Why is it not enough, for an API to be REST, to use noun URLs and return JSON?

Learning resources

• REST (MDN glossary) — a short definition.
• HTTP request methods (MDN) — the role of the methods.