API versioning: How to create handlers which return different data based on "Accept" header value

[leonklingele]

Hey there 😃

I was wondering what the best way of creating an API is which versions its endpoints by the request Accept / response Content-Type header values. Instead of using the version inside the URL (/v1/users vs. /v2/users) I want to follow REST more closely and use a single route (/users) instead. This route then returns different responses depending on which version the client asks for with the Accept header.

In OpenAPI jargon, I expect Huma to generate a spec like this:

UsersResponse:
  content:
    application/vnd.mynamespace.v1+json:
      schema:
        type: array
        items:
          $ref: "#/components/schemas/UsersV1Response"
    application/vnd.mynamespace.v2+json:
      schema:
        type: object
        properties:
          users:
            type: array
            items:
              $ref: "#/components/schemas/UsersV2UsersResponse"
          metadata:
              $ref: "#/components/schemas/UsersV1MetadataResponse"

I have seen that this is probably already doable by using a custom huma.Operation and setting the Responses field to include multiple Contents (with a Content-Type as key for the map) which each define a Schema which then in turn specifies how the data is going to be returned for the respective Content-Type the client asks for.

What would be the best way of doing this? To me this currently looks quite complicated to do, compared to including the version directly inside the route URL.

Any suggestions? :)

Thanks for helping & creating Huma, @danielgtaylor. It definitely rocks!

(Also see https://jsonapi.org/)

[leonklingele]

Apparently related to (a duplicate of?) #377 and #864.