RESTful API

Definition

A RESTful API is a web API style that models system capabilities as resources and uses standard HTTP semantics to operate on them. Instead of inventing custom verbs for every action, a RESTful design leans on nouns in URLs plus familiar methods such as GET, POST, PUT, PATCH, and DELETE.

---

Core Ideas

Resource-Oriented Design

• Use nouns, not verbs, in endpoint names
• Represent collections and individual resources clearly
• Keep URL structures predictable and consistent

Examples:

• GET /tickets
• GET /tickets/12
• POST /tickets
• PATCH /tickets/12
• DELETE /tickets/12

HTTP as the Contract

A RESTful API relies on HTTP for more than transport:

• methods express intent
• status codes communicate outcomes
• headers carry metadata for auth, caching, pagination, and content negotiation
• query parameters support filtering, sorting, field selection, and search

Design Principles from the Source Notes

• use SSL everywhere
• version the API explicitly
• prefer JSON for responses and request bodies
• define a consumable, consistent error payload
• support filtering, sorting, and pagination cleanly
• return useful representations after create/update operations
• document the API as if it were a product interface

Practical Trade-Offs

REST is popular because it is widely understood, browser-friendly, and easy to integrate with. But it is not the only style, and some operations fit awkwardly into pure CRUD resource models. Pragmatic API design sometimes accepts non-ideal but clear choices when they improve developer experience.

---

Common Concerns

Authentication and Security

• token-based authentication is preferred for stateless APIs
• OAuth2 is useful when delegation to third parties is required
• SSL/TLS is non-negotiable

Performance and Usability

• use pagination for large collections
• allow field limiting and embedding when practical
• expose caching via ETag or Last-Modified headers
• publish rate-limit headers and meaningful error responses

Platform Integration

RESTful APIs are often the boundary layer for:

• web and mobile clients
• microservices communication
• external partner integrations
• serverless API gateways

---

Relationships

• Microservices — microservices frequently communicate through RESTful HTTP interfaces
• Serverless — serverless applications often expose RESTful endpoints through API Gateway
• Cloud & AWS Infrastructure — AWS services such as API Gateway support RESTful API delivery
• Software Architecture & Distributed Systems — API design is a core interface concern in distributed systems

---

References

• about restful api
• Best Practices for Designing a Pragmatic RESTful API
• to be considered in Hexagonal RESTful API