API Guidelines
  • adidas API Guidelines
  • General Guidelines
    • Introduction
    • API First
    • Contract
    • Immutability
    • Robustness
    • Common Data Types
    • Version Control System
    • Minimal API Surface
    • Rules for Extending
    • JSON
    • Security
    • Tooling
  • REST API Guidelines
    • Introduction
    • Core REST Principles
      • OpenAPI Specification
      • API Design Platform
      • Design Maturity
      • Testing
    • Protocol
      • HTTP
      • TLS
      • Separate Concerns
      • Request Methods
      • Status Codes
    • Message
      • Message Formats
      • Content Negotiation
      • HAL
      • Problem Detail
      • Foreign Key Relations
    • Application
      • Corporate Data Model
      • Common Data Types
    • Execution
      • Pagination
      • Long Running Tasks
        • Polling
        • Callback
        • Files Upload
      • Batch Operations
      • Search Requests
      • Query Requests with Large Inputs
      • Choosing Fields and Embedded Resources
      • Localization
      • Rate Limiting
      • Caching
      • Testing Enviroments
    • Evolution
      • Naming Conventions
      • Reserved Identifiers
      • URI Structure
      • Changes and Versioning
      • Phasing out Old Versions
    • Guides
      • API Testing CI Environment
      • Complete API Development
    • API Clients
      • Loose Coupling
    • Further References
  • Asynchronous API Guidelines
    • Introduction
    • Core Asynchronous Principles
      • Event Driven Architectures
      • Messages
        • Commands
        • Queries
        • Events
          • Events as Notifications
          • Events to Replicate Data
      • Protocols
      • Coupling
      • Bounded Context
      • Stream Processing
      • Naming Conventions
      • Tooling
        • Editors
        • Command Line Interface (CLI)
        • Generators
    • Kafka Asynchronous Guidelines
      • Introduction
        • Why AsyncAPI?
      • AsyncAPI Version
      • Internal vs Public Specifications
      • Key/Value Format
      • Message Headers
      • Specification Granularity
      • Self-Contained Specifications
        • Meaningful Descriptions
      • Schema Data Evolution
        • Backward Compatibility
        • Forward Compatibility
        • Full Compatibility
      • Automatic Schema Registration
      • Contact Information
      • AsyncAPI ID
      • Servers
      • Channels
      • Schemas
      • Security Schemes
      • External Docs
Powered by GitBook
On this page
  • Example 1
  • Example 2
  1. REST API Guidelines
  2. Protocol

Separate Concerns

Every API using HTTP/S MUST precisely follow the concern separation of an HTTP message:

  1. A resource identifier–URI MUST be used to indicate identity only

  2. HTTP request method MUST be used to communicate the action semantics (intent and safety)

  3. HTTP response status code MUST be used to communicate the information about the result of the attempt to understand and satisfy the request

  4. HTTP message body MUST be used to transfer the message content

  5. HTTP message headers MUST be used to transfer the metadata about the message and its content

  6. URI query parameter SHOULD NOT be used to transfer metadata

Example 1

The rule

A resource identifier–URI MUST be used to indicate identity only

implies there MUST NOT be any information about the representation media type, version of the resource or anything else in the URI.

For example, URIs /greeting.json or /v2.1.3/greeting are illegal as they are not used for identification of a resource only but they convey the information about representation format or version. URIs are not meant to carry any other information but the identifier of the resource.

Example 2

The rule

HTTP message body MUST be used to transfer the message content

Implies an HTTP GET request MUST NOT use HTTP message body to identify the resource. For example a request:

GET /greeting HTTP/1.1
Content-Type: application/json
...


{
    "filter": "string"
    "depth": 3
}

is not acceptable (ignoring the fact that HTTP GET method shouldn't have the body). To express identity use URI and query parameters instead e.g. /greeting?filter=string&depth=3.

Keep things simple while designing by separating the concerns between the different parts of the request and response cycle. Keeping simple rules here allows for greater focus on larger and harder problems.

Requests and responses will be made to address a particular resource or collection. Use the path to indicate identity, the body to transfer the contents and headers to communicate metadata. Query params may be used as a means to pass header information also in edge cases, but headers are preferred as they are more flexible and can convey more diverse information.

PreviousTLSNextRequest Methods

Last updated 10 months ago

–

Heroku HTTP API Design Guide