Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
GitHub is where the world builds software
Millions of developers and companies build, ship, and maintain their software on GitHub — the largest and most advanced development platform in the world.
media type for request with existing vendor tree #1020
We have an internal API that uses an
We're writing a
What the correct way to structure the Accept header with two vendor trees?
I've been reading a bunch, but I can't figure out
Can you provide some guidance for this?
A media type in the vendor tree is used in the
If the client wants to indicate that it prefers one type over another, it can use the
(The above header indicates that JSONAPI is preferred over vnd.ourcompany.v3+json. See here for more details on "q" values.)
@bf4 I re-read your question here after seeing your comment in #406, and I think I misunderstood it originally. Any media types listed in the
@ethanresnick Let me see if I understand you
Given a company has an API And that API use the JSON API (media type: `application/vnd.api+json`) And that the company is making breaking changes to the existing API And so would like to use version the changes Then the company should continue to specify their API media type, as it has not changed And communicate the version in the URI (`example.com/v3/`) or domain (`api3.example.com/`), via custom headers ( `X-API-Version: 3`, `Vary: X-API-Version`) OR ask clients to understand a custom media type `application/vnd.ourcompany.v3+json` as including JSON API BUT not as `application/vnd.ourcompany.v3+json, application/vnd.api+json` nor `application/vnd.ourcompany.v3+json, ext=jsonapi` nor `application/vnd.api+json; ext=ourcompany; version=3.0` nor `application/vnd.api+json; version = 3.0` And that this is how users of JSON API should expect their APIs to evolve
So, I think I also misunderstood the spec w/r/t content negotiation.
The client must sends a request with
But, regarding the
So, the only requirement on the
So, there'd be no problem with a request with the headers
The only problem there is that we must interpret
@steveklabnik xrefs for a quick timeline of changes in points of view on the subject:
tl;dr Accept is for media types. Unless each API version happens to be a new media type, URL versioning is less confusing and just works better, if you need versioning at all
and for fun @brandur on REST/Hypermedia vs. GraphQL/RPC