What are RESTful Web APIs?
REST
• REpresentational State Transfer
• First presented in Roy Fielding’s dissertation
• It is an architectural style, NOT a protocol or technology.
• Centered Around Five Principles
• There is an optional 6th
• Not all principles are always implemented.
• Web services may not be “perfectly” REST (REST-like ☺)
1. Uniform Interface
• All interactions follow a standardized approach, making the system
simple and predictable
• Lowers the learning curve and decouples clients and servers.
• Implemented with four constraints:
• Resource identification in requests
• Using URIs: GET /users/123 → retrieves user with ID 123
• Resource manipulation through representations
• Modify resources by sending their representations (often JSON or XML)
• Self-descriptive messages
• Resource representations should carry information for how to process the message and
additional actions that the client can perform on the resource.
• Hypermedia as the engine of application state (HATEOAS)
• Provide hyperlinks within API responses, guiding the client on how to interact with the API
and discover subsequent actions and resources
• Often not implemented fully…or at all
2. Client-Server
• The client-server design pattern enforces the separation of
concerns, allowing the client and server components to evolve
independently of each other.
• Client
• Initiates Requests
• Supports display/presentation of information
• Server
• Processes Requests
• Business Logic / Data Storage and Retrieval
• Send Response to Client
3. Stateless
• Every HTTP request happens in complete isolation.
• The client provides all necessary information to understand and
complete a request with the request itself.
• The client, NOT the server, stores session state between requests
• Cookies, local storage, etc.
4. Cacheable
• Storage of data or results from a response to be reused in place of
a new request to the server
• Responses should indicate whether they are cacheable (and for
how long) to improve performance and scalability
• Why use Caching?
• Reduces bandwidth (network load/traffic)
• Reduces latency
• Reduces server load
• Can hide network failures
5. Layered System
• Clients do not need to be aware whether they are communicating
directly with the server or through intermediaries
• Proxies (a server that acts as an intermediary on behalf of another)
• Load Balancers (software or hardware to distribute traffic across servers)
• Gateways (a server that routes traffic requests to multiple services)
• Caches / Content Delivery Networks (CDNs)
• Example:
• Browser → CDN (caches static responses) → API Gateway → App Server →
Database
• The client only knows that it received what it requested.
6. Code on Demand (Optional)
• Servers can extend client functionality by sending code to the client for
execution.
• HTML / CSS to be displayed
• JavaScript to be executed.
• Specialized Code
• Calculating taxes from different countries
• Can send code specifically for the region to the client without having to send code that
works “everywhere”.
• Tax rules change? Cool, update the server only, not every client.
• Lazy loading
Web APIs
• Application Programmer Interface (API)
• Generally, send Data (JSON or XML) only.
• Consumed by manual (people) or automated (other servers, bots, etc.) clients.
• Uses URIs along with HTTP Methods to provide resources.
• URIs are often called endpoints.
• Can be used for:
• Data Acquisition
• Actions
• Both!
Examples!
Example: JSONPlaceholder (GET)
REQUEST
curl -X GET "[Link] \
-H "Accept: application/json"
RESPONSE
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
"body": "quia et suscipit [...]"
}
As the name implies, JSONPlaceholder simulates these web responses to create a realistic environment.
Example: JSONPlaceholder (POST)
REQUEST
curl -X POST "[Link] \
-H "Content-Type: application/json" \
-d '{"title": "Hello World", "body": "My first post", "userId": 1}'
RESPONSE
{
"title": "Hello World",
"body": "My first post",
"userId": 1,
"id": 101
}
Example: JSONPlaceholder (PUT)
REQUEST
curl -X PUT "[Link] \
-H "Content-Type: application/json" \
-d '{"id": 1, "title": "Updated Title", "body": "Updated body", "userId": 1}'
RESPONSE
{
"id": 1,
"title": "Updated Title",
"body": "Updated body",
"userId": 1
}
Example: JSONPlaceholder (DELETE)
REQUEST
curl -X DELETE "[Link]
RESPONSE
{}
