Representational State Transfer (REST) is an architectural style for designing networked applications. It is a set of principles that guide the design of web services, emphasizing the use of standard HTTP methods (GET, POST, PUT, DELETE) to interact with resources identified by URLs.
This page provides practical examples of common REST API operations, demonstrating how to make requests and interpret responses. These examples are illustrative and may need adaptation based on specific API documentation.
The GET method is used to retrieve data from a server. It is idempotent, meaning that making the same request multiple times will have the same effect as making it once.
GET /api/v1/users
Fetches a list of all users.
Sample Response (JSON):
[
{
"id": "user-123",
"username": "alice_wonder",
"email": "alice@example.com",
"isActive": true
},
{
"id": "user-456",
"username": "bob_builder",
"email": "bob@example.com",
"isActive": false
}
]
To retrieve a single resource, you typically include its unique identifier in the URL path.
GET /api/v1/users/user-123
Fetches details for a specific user with ID "user-123".
Sample Response (JSON):
{
"id": "user-123",
"username": "alice_wonder",
"email": "alice@example.com",
"firstName": "Alice",
"lastName": "Wonderland",
"createdAt": "2023-10-27T10:00:00Z",
"isActive": true
}
The POST method is used to submit data to be processed to a specified resource. This often results in the creation of a new resource. The request body typically contains the data for the new resource in JSON format.
POST /api/v1/users
Creates a new user.
Request Body:
{
"username": "charlie_chaplin",
"email": "charlie@example.com",
"firstName": "Charlie",
"lastName": "Chaplin"
}
Sample Response (JSON - Created Resource):
Status Code: 201 Created
{
"id": "user-789",
"username": "charlie_chaplin",
"email": "charlie@example.com",
"firstName": "Charlie",
"lastName": "Chaplin",
"createdAt": "2023-10-27T11:00:00Z",
"isActive": true
}
The PUT method is used to update an existing resource or create it if it doesn't exist. It is generally used to replace the entire resource.
PUT /api/v1/users/user-123
Updates the user with ID "user-123".
Request Body:
{
"username": "alice_wonder",
"email": "alice.w@example.com",
"firstName": "Alice",
"lastName": "Wonderland",
"isActive": false
}
Sample Response (JSON - Updated Resource):
Status Code: 200 OK
{
"id": "user-123",
"username": "alice_wonder",
"email": "alice.w@example.com",
"firstName": "Alice",
"lastName": "Wonderland",
"createdAt": "2023-10-27T10:00:00Z",
"isActive": false
}
The PATCH method is used to apply partial modifications to a resource. Unlike PUT, it only sends the fields that need to be changed.
PATCH /api/v1/users/user-123
Partially updates the user with ID "user-123".
Request Body:
{
"isActive": true
}
Sample Response (JSON - Updated Resource):
Status Code: 200 OK
{
"id": "user-123",
"username": "alice_wonder",
"email": "alice.w@example.com",
"firstName": "Alice",
"lastName": "Wonderland",
"createdAt": "2023-10-27T10:00:00Z",
"isActive": true
}
The DELETE method is used to remove a resource from the server.
DELETE /api/v1/users/user-456
Deletes the user with ID "user-456".
Sample Response:
Status Code: 204 No Content
A 204 status code indicates that the request was successful but there is no content to send back in the response body.
REST APIs often use query parameters in the URL to filter, sort, or paginate results.
GET /api/v1/products?category=electronics&limit=10&offset=20
Fetches a list of products in the 'electronics' category, with results limited to 10 items and starting from the 21st item (offset 20).
Sample Response (JSON - Paginated List):
{
"total": 150,
"count": 10,
"next": "/api/v1/products?category=electronics&limit=10&offset=30",
"previous": "/api/v1/products?category=electronics&limit=10&offset=10",
"results": [
{
"id": "prod-001",
"name": "Smartphone X",
"price": 999.99,
"category": "electronics"
},
// ... 9 more product objects
]
}
/users, /products)./api/v1/).