Recipe #57: Making IIIF Presentation API v2 and v3 manifests available at the same URL

[glenrobson]

Links

• Original Issue: Publishing v2 and v3 manifests at the same time for a single resource cookbook-recipes#57
• Pull Request: Recipe #0057: v2 and v3 manifests at the same URL cookbook-recipes#181
• Preview: https://preview.iiif.io/cookbook/0057-conneg/recipe/0057-publishing-v2-and-v3/

Background and Summary

This recipe looks at a method for providing access to a v2 and v3 manifest using the same URL and content negociation.

Voting and changes

We welcome comments on the recipe and as well as voting +1, confused face or -1 feel free to add comments to this issue. If this issue is approved then the author will take account of the comments before we merge the branch in to the master cookbook branch.

If the recipe is rejected by the TRC then we will make the changes requested and resubmit it to a future TRC meeting. If you feel that your comments are substantial enough that the recipe should be looked at again by the TRC after the changes have been made please vote -1 (thumbs down). A confused face is treated as abstaining.

Changes to the recipe will only be made after the TRC voting process has concluded.

[tristanr-cogapp]

I would prefer it if the content-type header in the sample response followed the SHOULD part of the spec, i.e. instead of

content-type: application/json

It returned e.g.

content-type: application/ld+json;profile=http://iiif.io/api/presentation/2/context.json

However, this is not a deal breaker as this is only a recommendation of the spec, rather than a full requirement. And clients should check the actual text returned as the definitive answer as to which version is being supplied.

[nfreire]

A few small suggestions:

In the first occurrence of "Content Negotiation" I suggest writing "HTTP Content Negotiation" to make it clear for the reader that this is an HTTP feature, not something specific to IIIF.

In the third paragraph of the Implementation Notes, "version 2 or version 3" read like they are refering to JSON-LD version.
So maybe change a bit the sentence from:
"...be asked to vary its response for either a version 2 or version 3 formatted JSON-LD."
to:
"...be asked to vary its response for either a version 2 or version 3 of a IIIF resource formatted in JSON-LD."

In the fourth paragraph of the Implementation Notes, a reference should be made to the particular section of the IIIF spec:
https://iiif.io/api/presentation/3.0/#63-responses

[triplingual]

(Standard note that I upvoted my own recipe)

[robcast]

A small clarification question: in the restrictions section the recipe says "Perhaps the most notable is that web browsers do not allow clients to vary their Accept headers, so viewing IIIF resources in a browser is restricted to viewing the server’s default response." Is this sentence talking about Javascript clients or only about viewing a Manifest by putting the URI in the addressbar of the browser?

I was under the impression that it is possible for a browser-based client to set the Accept header on a Javascript fetch request (https://developer.mozilla.org/en-US/docs/Web/API/Headers) as it is not a forbidden header (https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_request_header). But I haven't tried it.

[zimeon]

I strongly support Tristan's suggestion that the HTTP response examples should give the matching type+profile in the Content-Type. This not only matches the SHOULD in the specification but make the example much clearer.

[regisrob]

In the first paragraph of the implementation notes, I wonder if the mention ... (both Presentation and Image API) ... is really relevant here, since the recipe only deals with content negociation for manifests. The example manifests do not have an Image API service, and even if we had Image API v2 or v3 in one manifest or the other it would not change anything to the recipe, if I am not wrong...

[glenrobson]

Issue 135 (Recipe #57: Making IIIF Presentation API v2 and v3 manifests available at the same URL)

+1: 11 [akrishnan15 glenrobson irv kirschbombe ksclarke nfreire regisrob robcast tpendragon triplingual zimeon]
0: 1 [annhanlon]
-1: 0 []
Not TRC: 0 []
Ineligible: 4 [LlGC-iir markpatton mixterj tristanr-cogapp]

Result: 11 / 12 = 0.92

Super majority is in favor, issue is approved

[triplingual]

Post-Approval Changes

• first occurrence of "Content Negotiation" ==> "HTTP Content Negotiation"
• "version 2 or version 3 formatted JSON-LD." ==> "version 2 or version 3 of a IIIF resource formatted in JSON-LD."
• fourth graf of Implementation Notes, make reference to https://iiif.io/api/presentation/3.0/#63-responses
• Edit restrictions to narrow focus to what the conventional non-technical user can/can't/will/won't do, away from browser/client capabilities, since they are more complicated
• Edit first graf of Implementation Notes to make it clear the recipe is dealing with prezi but note perhaps that Content Negotiation / similar mechanisms apply to the Image API

[triplingual]

Additionally, I added viewer links for the v2 manifest so recipe readers can see any differences for themselves.