Introduction to REST Interfaces
A REST interface, usually called a REST API, is a way for programs to exchange data over HTTP by treating everything as a resource with its own URL. A React frontend, a mobile app or another server can ask for a list of products, create an order or delete a comment by sending standard HTTP requests to predictable addresses. REST is the most common style for web APIs, so understanding it makes almost any backend easier to work with.
Resources and URLs
In REST, a resource is any thing your application manages: users, posts, orders, invoices. Each collection gets a URL, and each individual item gets a URL under it.
/api/booksis the collection of all books./api/books/17is the single book with id 17./api/books/17/reviewsis the collection of reviews belonging to that book.
URLs use nouns, usually plural. The action you want to perform is not part of the URL; it comes from the HTTP method.
Methods describe the action
| Method | URL | Action | Typical success code |
|---|---|---|---|
| GET | /api/books | List books | 200 OK |
| GET | /api/books/17 | Get one book | 200 OK |
| POST | /api/books | Create a book | 201 Created |
| PUT | /api/books/17 | Replace the book | 200 OK |
| PATCH | /api/books/17 | Update some fields | 200 OK |
| DELETE | /api/books/17 | Remove the book | 204 No Content |
This mapping lines up with the four basic data operations, often called CRUD: create, read, update and delete. Combined with the status codes from the previous lesson, a client can understand the result of any request without reading custom documentation for each endpoint.
What a request and response look like
Data is usually sent as JSON. Here is a request to create a book and the server's reply:
POST /api/books HTTP/1.1
Host: shop.example
Content-Type: application/json
{ "title": "Clean Code", "author": "Robert C. Martin" }
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/books/18
{ "id": 18, "title": "Clean Code", "author": "Robert C. Martin" }
The JSON is a representation of the resource. The server might store it in a database table with a very different shape; the client only ever sees this representation.
Statelessness in one sentence
Each request must carry everything the server needs to handle it, including authentication like a token in the Authorization header. The server does not remember earlier requests from the same client. This makes REST services easier to scale, because any server instance can handle any request. The next lesson looks at this and the other characteristics of REST in more detail.
Design mistakes beginners make
The most frequent one is putting verbs into URLs, such as /api/getBooks, /api/createBook or /api/deleteBook?id=17. This ignores HTTP methods and makes every endpoint a special case. Use GET /api/books and DELETE /api/books/17 instead.
The second is using GET to change data, for example GET /api/books/17/delete. GET requests are expected to be safe: browsers may prefetch them, crawlers follow them and caches store them. A link crawler could delete your data. Any change belongs in POST, PUT, PATCH or DELETE.
Finally, returning 200 with an error message in the body hides failures from clients. Use proper codes such as 400, 404 or 500.
In a nutshell
REST gives each resource a noun-based URL, uses HTTP methods for actions, exchanges JSON representations, and keeps every request self-contained. Once you recognise this pattern, reading or designing an API becomes much more predictable.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.