Understanding REST API Basics and How to Use It
What is an API?
Before explaining REST API, let's first look at what an API is.
API (Application Programming Interface) refers to a set of rules or interfaces that enable interaction between software or systems, such as Google Maps API, etc.
By utilizing APIs, developers can perform specific tasks or access data from external services without having to implement complex features themselves.
The main advantages of APIs are:
- Reusability: Reuse already developed features to save development time and costs.
- Efficiency: Complex features can be implemented easily and quickly, making the development process more efficient.
- Interoperability: Data and functionality can be easily shared across various systems, languages, and platforms.
- Security: Access to data and features can be controlled through APIs, and user authentication and authorization can be managed.
REST API
REST API stands for Representational State Transfer and is one of the methods for exchanging data between client and server in web-based communication.
A REST API refers to an API designed by applying REST principles, and most modern services provide REST APIs.
Using REST API, various resources on the web can be managed using standard HTTP methods.
These resources can generally take many forms such as text, images, service processing results, etc.
In other words, a RESTful API uses the web's fundamental protocol HTTP to access service resources and perform data exchange.
Let's summarize the core characteristics of REST API and compare them with other API styles in a table.
| Characteristic | REST API Description | Comparison with Other API Styles |
|---|---|---|
| Client-Server Structure | Client and server are clearly separated. Client focuses on UI, server handles data and backend logic. | Common structure in most API styles. |
| Stateless | Each request is independent; server does not store client state information. All necessary information must be included in each request. | In styles like SOAP, state may be maintained to keep session information. |
| Cacheable | Responses must be explicitly marked as cacheable. This allows clients to reuse responses, improving efficiency. | Caching is possible in other styles too, but REST treats it as a core principle. |
| Layered System | Client doesn't need to communicate directly with the end server; requests can go through intermediate servers. | Layering is possible in other styles, but REST defines it more explicitly. |
| Uniform Interface | REST APIs interact with services through representations of resources. | Resources are identified via URIs, and actions are defined using HTTP methods (GET, POST, etc.). Other styles like SOAP usually use a single endpoint with actions specified in messages. |
| Code on Demand (optional) | Server can send executable code to the client (e.g. JavaScript). This is an optional feature. | Rarely used in most API styles. |
Core Principles of REST API
-
Actions on resources must be expressed using the following HTTP methods.
-
URIs should represent resources — resource names should use nouns, not verbs.
| Operation | HTTP Method | URI Example | Description |
|---|---|---|---|
| Retrieve resource list | GET | /users | Retrieves information of all users. |
| Retrieve specific resource | GET | /users/{userId} | Retrieves information of a specific user by ID. |
| Create resource | POST | /users | Creates a new user. Data is included in the request body. |
| Update resource | PUT | /users/{userId} | Updates information of a specific user by ID. Data is included in the request body. |
| Partial update | PATCH | /users/{userId} | Updates only specific fields of a user by ID. Data is included in the request body. |
| Delete resource | DELETE | /users/{userId} | Deletes a specific user by ID. |
Example – Handling User Information with JavaScript Code
- Retrieving user information (GET request)
fetch('https://example.com/api/users/1', {
method: 'GET',
headers: {
'Accept': 'application/json' // Content type the client wants to receive
}
})
.then(response => {
if (response.ok) {
return response.json(); // Parse response as JSON
}
throw new Error('Network response was not ok.');
})
.then(userData => console.log(userData)) // Process user data
.catch(error => console.error('There has been a problem with your fetch operation:', error));
- Creating user information (POST request)
fetch('https://example.com/api/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json', // Content type of the request body
'Accept': 'application/json' // Content type the client wants to receive
},
body: JSON.stringify({
name: 'John Doe',
email: 'john.doe@example.com'
})
})
.then(response => {
if (response.ok) {
return response.json();
}
throw new Error('Network response was not ok.');
})
.then(newUserData => console.log(newUserData)) // Process newly created user data
.catch(error => console.error('There has been a problem with your fetch operation:', error));
Related Posts in Series
Collapse- 1. Understanding REST API Basics and How to Use It