Skip to main content

IPA-900: Handling Multiple Content Types in Atlas Programmatic Clients

Handling multiple content types in API responses is essential for providing flexibility for programmatic clients. Guidance outlines best practices for managing multiple content types for request and response bodies for Atlas programmatic clients with a particular focus on scenarios where a 2xx HTTP response is returned.

State

Experimental

Guidance​

Content Type Preference​

  • When an API response includes multiple content types, all OpenAPI-based programmatic clients must support application/vnd.atlas.YYYY-MM-DD+json as the default content type.
    • The JSON format is preferred because it allows for the inclusion of additional metadata without introducing breaking changes.
    • The YYYY-MM-DD in the content type should correspond to the date representing the latest version of the API.
    • If the API does not return a JSON content type, the default content type must include versioned headers, such as application/vnd.atlas.YYYY-MM-DD+csv.

Examples​

  1. If an API supports both application/vnd.atlas.YYYY-MM-DD+json and application/vnd.atlas.YYYY-MM-DD+csv, the application/vnd.atlas.YYYY-MM-DD+json content type should be preferred and handled by the SDK.
  2. If an API supports only application/vnd.atlas.YYYY-MM-DD+json, this content type should be preferred and handled by the SDK.

Supporting Multiple Content Types​

  • SDKs and clients may offer the capability to request specific content types from the list of all supported response content types.
    • This feature enhances flexibility and allows clients to specify their preferred format.