Content Negotiation

The Accept request header is the client's primary mechanism for specifying its preferred media types (MIME types) for the response. The server uses this to select from its available representations.

• Syntax: Accept: <type>/<subtype>; q=<quality factor>
• Quality Values (q): A number from 0 to 1 indicating relative preference (e.g., application/json; q=0.9, text/xml; q=0.5).
• Wildcards: */* accepts any type; application/* accepts any subtype of application.
• Example: Accept: application/json, application/vnd.api+json; q=0.9, text/html; q=0.8

The Content-Type entity header indicates the media type of the actual resource sent in the request or response body. It is critical for the recipient to parse the payload correctly.

• Request Context: In a POST or PUT, tells the server the format of the incoming data.
• Response Context: In a server reply, confirms the format chosen from the Accept header options.
• Syntax: Content-Type: <type>/<subtype> often with a charset parameter (e.g., Content-Type: application/json; charset=utf-8).
• Schema Link: The format should match the schema defined for that endpoint in the OpenAPI specification.

Beyond media type, clients can negotiate on other resource characteristics using specific Accept-* headers, allowing for more granular agreement.

Key headers include:

• Accept-Charset: Preferred character sets (e.g., utf-8, iso-8859-1). Largely deprecated in favor of charset within Content-Type.
• Accept-Encoding: Preferred content codings for compression (e.g., gzip, deflate, br). Essential for performance.
• Accept-Language: Preferred natural languages for the response (e.g., en-US, fr, de; q=0.7).
• Accept-Version or Custom Headers: Used for API version negotiation, often as a custom header like Accept-Version: v2.1 or within the Accept header as a vendor MIME type.

Content negotiation operates in two primary modes, each with different trade-offs for API design and client complexity.

• Server-Driven Negotiation: The default HTTP model. The client sends Accept headers, and the server selects the appropriate representation using an internal algorithm. It is simple for clients but can lead to opaque selection logic.
• Agent-Driven (Content Choice) Negotiation: The server returns a list of available representations (often with URLs and metadata), and the client explicitly chooses. This is more explicit and cache-friendly but requires multiple round trips. It can be implemented using HTTP 300 Multiple Choices or documented via API schema links.

API schemas like OpenAPI formally define the negotiable content types for each operation, enabling automated validation and tooling.

• OpenAPI produces/consumes: At the operation or global level, these lists define the MIME types a server can produce and consume, respectively.
• Request/Response Validation: Middleware or API gateways can validate that the Content-Type of an incoming request matches a type in the consumes list and that the Accept header's preferences can be satisfied by the produces list.
• Code Generation: SDKs generated from the schema will be configured to send the correct Accept and Content-Type headers by default.

Effective negotiation includes strategies for handling mismatches and failures to ensure robust communication between clients and servers.

• Default Representations: Servers should define a default media type (e.g., application/json) to use when Accept: */* is sent or when no match is found.
• 406 Not Acceptable: The proper HTTP status code when the server cannot fulfill the Accept header request. The response may include a Content-Type header describing what is available.
• Graceful Degradation: Clients can list multiple types in preference order, allowing the server to 'fall back' to a less-preferred but supported format.
• Vendor MIME Types: Used for versioning (e.g., application/vnd.company.user.v2+json), allowing clients to request a specific API version via the Accept header.

The OpenAPI Specification (OAS) is the industry-standard, machine-readable format for describing RESTful APIs. It defines endpoints, HTTP methods, request/response schemas, parameters, and authentication mechanisms. For AI agents, an OpenAPI document acts as a comprehensive instruction manual, enabling dynamic invocation of API operations without hardcoded integrations.

• Core Components: Paths, Operations, Parameters, Request Bodies, Responses, and Security Schemes.
• Machine-Readable: Typically written in YAML or JSON, allowing for automated code generation of client SDKs and server stubs.
• Foundation for Tool Calling: AI agent frameworks ingest OpenAPI specs to discover available tools and understand required data formats for structured output guarantees.

JSON Schema is a declarative language for annotating and validating JSON documents. It defines the expected structure, data types, formats, and constraints (e.g., minimum values, required fields, regular expression patterns). In API contexts, JSON Schema is used within OpenAPI to define the precise shape of request and response payloads.

• Validation Core: Enables schema validation to ensure data conforms to contract before processing.
• Type Definitions: Provides rigorous type definitions for properties (string, number, array, object).
• Modularity: Uses the $ref keyword to reference and reuse common definitions, promoting consistency and reducing duplication in large API specs.

An API contract is the formal, shared agreement between a service provider and its consumers. It is the single source of truth for how an API behaves, typically embodied as an OpenAPI document. This contract governs all interactions, ensuring predictability and enabling contract testing.

• Machine-Readable Agreement: Specifies endpoints, data models, error formats, and authentication.
• Enables Automation: Drives documentation, mock servers, and client library generation.
• Foundation for Reliability: For AI agents, adherence to the contract via request/response validation is critical for correct tool calling and API execution. Breaches of the contract lead to integration failures.

Dynamic invocation is the runtime capability of a system (like an AI agent) to construct and execute API calls by interpreting a machine-readable schema, rather than using pre-compiled, static client code. The agent reads the API spec, selects an operation, builds a compliant request payload, and handles the response.

• Schema-Driven: Relies entirely on ingested OpenAPI specs and JSON Schema definitions.
• Flexibility: Allows the agent to interact with new or updated APIs without code changes, provided the schema is available.
• Core to Agentic Systems: This is the fundamental mechanism behind AI tool discovery and registration, enabling agents to autonomously extend their capabilities.

Schema validation is the automated process of verifying that a piece of data—such as an API request body generated by an AI agent or a response from a backend service—conforms to the structure and rules defined in a formal schema. This is a critical guardrail for secure and reliable API execution.

• Pre-Execution Check: Validates agent-generated parameters against the OpenAPI spec before the HTTP call is made, preventing malformed requests.
• Post-Execution Check: Validates incoming server responses to ensure they match the expected format before the agent processes the data.
• Enforces Correctness: Catches type mismatches, missing required fields, and constraint violations, directly supporting error handling and retry logic.