πŸ“š Protocol Docs

RESTful API

RESTful API describes an approach to interface design introduced by Roy Fielding in his 2000 doctoral dissertation. The core idea is simple: treat business capabilities as addressable resources, then rely on HTTP's own vocabulary β€” methods, URIs, and status codes β€” to manipulate those resources, covering the usual create/read/update/delete operations.

Principles Behind REST

  • Stateless: Each request is self-contained, carrying whatever the server needs, including credentials.
  • Separation of concerns: Presentation lives on the client; data and logic live on the server.
  • Uniform interface: Standard HTTP verbs such as GET, POST, PUT and DELETE express every action.
  • Cache friendly: Responses may be flagged as cacheable to save bandwidth and load.
  • Layered architecture: Proxies and load balancers can be inserted without breaking clients.

HTTP Verbs

  • GET: Read a resource; the server state is left untouched.
  • POST: Create a resource or submit data that triggers processing.
  • PUT: Replace an existing resource with the uploaded representation.
  • DELETE: Remove the target resource.
  • PATCH: Apply a partial change to a resource.

Designing Resource URLs

URIs name resources and nothing else β€” actions belong to HTTP methods. Plural nouns and path nesting express collections and ownership. A book API might look like this:

  • GET /books: List all books.
  • GET /books/{id}: Retrieve one book.
  • POST /books: Add a book.
  • PUT /books/{id}: Replace a book.
  • DELETE /books/{id}: Delete a book.

Reading HTTP Status Codes

Every REST response announces its outcome through a status code:

  • 200 OK: Success, with a payload.
  • 201 Created: A new resource was created.
  • 204 No Content: Success with an empty body.
  • 400 Bad Request: The request could not be understood.
  • 401 Unauthorized: Authentication is missing or invalid.
  • 404 Not Found: The resource does not exist.
  • 500 Internal Server Error: Something failed server-side.

Wrap-Up

Because REST builds on conventions everyone already knows, it keeps integration simple, scales across teams and systems, and remains a reliable choice for APIs of any size.

Next: Shadowsocks β†’