-
Notifications
You must be signed in to change notification settings - Fork 678
Introduction to REST APIs
A REST API (Representational State Transfer API) is a widely adopted architectural style for building web services that communicate over HTTP. It provides a set of guidelines for creating stateless, client-server APIs that expose data and functionality as resources identified by URLs.
Before diving into REST, it helps to be familiar with:
HTTP – the protocol used to transfer data on the web
APIs – interfaces that allow software systems to interact
In REST, all data and functionality are treated as resources — logical entities that can be created, read, updated, and deleted. Each resource is identified by a unique URL, and clients interact with them using standard HTTP methods:
| HTTP Method | Action |
|---|---|
| GET | Retrieve a resource |
| POST | Create a new resource |
| PUT | Update a resource |
| DELETE | Remove a resource |
For example, an API managing user data might expose the following URL:
GET /users/john_doe
This retrieves the resource representing the user with the ID john_doe.
The client is any system (such as a browser or a backend service) that initiates API requests. It could be a frontend application, a script written by a developer, or another service within a distributed system.
A resource is any object or data entity exposed by the API — such as a user, a blog post, or an order. Each resource must be uniquely addressable via a URL, and its current state is transferred to the client during interaction.
When a client requests a resource, the server responds with a representation of that resource’s current state — typically in JSON or XML format. For example:
{
"id": "john_doe",
"name": "John Doe",
"email": "[email protected]"
}
This representation reflects the state of the user resource at the time of the request.
When designing or consuming a REST API, two components are essential:
Example: /users/123 refers to the user with ID 123.
Example: GET on /users/123 fetches the details of that user.
Together, they allow clients to perform precise operations on resources in a predictable and uniform way.
The OpenAPI Specification (OAS) is a standardized, language-agnostic format for describing RESTful APIs. It enables both humans and machines to understand the capabilities of a service without access to source code or additional documentation. WSO2 API Manager supports both OpenAPI 2.0 (formerly Swagger 2.0) and OpenAPI 3.0 specifications for defining APIs.
References :
These specifications can be used when importing or exporting API definitions, generating client/server SDKs, and integrating with developer tools.