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
  1. REST API Guidelines
  2. Message

Content Negotiation

PreviousMessage FormatsNextHAL

Last updated 11 months ago

Every API MUST implement and every API Consumer MUST use the where a representation of a resource is requested.

NOTE: The content negotiation plays the key role in evolving an API, change management and versioning.

Example

A client is programmed to understand the application/vnd.example.resource+json; version=2 message format semantics. The client requests a representation of the /greeting resource in desired the media type (including its version) from the server:

GET /greeting HTTP/1.1
Accept: application/vnd.example.resource+json; version=2
...

The server can provide only a newer version of the requested media type version=2.1.3. But since the newer version is backward compatible with the requested version=2 (related: Changes & Versioning) it can satisfy the request and responds:

HTTP/1.1 200 OK
Content-Type: application/vnd.example.resource+json; version=2.1.3
...

NOTE: A server that doesn't have the requested representation media type available MUST respond with the HTTP Status Code 406 Not Acceptable.

NOTE: A server MAY have multiple choices available and MAY respond with the 300 Multiple Choices response. In which case client SHOULD choose from the presented choices.

You can read more about content negotiation at .

HTTP content negotiation
MDN Content negotiation