Recipe #0057: v2 and v3 manifests at the same URL

[ahankinson]

This is a first pass at a cookbook recipe for #57, presenting v2 and v3 responses at the same URL.

Fixes #57

[glenrobson]

Recipe available at: https://preview.iiif.io/cookbook/0057-conneg/recipe/0057-publishing-v2-and-v3/

[ahankinson]

@glenrobson I believe progress on this recipe is blocked until we have a way of requesting the manifests from the Cookbook infrastructure.

[glenrobson]

I've been thinking about how to do this... Could you hard code the manifest ID for both files to:

https://iiif.io/api/cookbook/recipe/0057-publishing-v2-and-v3/manifest.json

This will be the live URL once its in master and also part of the live IIIF infrastructure which has a reverse proxy in the middle. I can set this to proxy from preview until its been approved.

[ahankinson]

I think that's what I've done -- I just don't know the value to use for example.iiif.io in the body of the text.

[glenrobson]

This link should now resolve to the correct manifest if you pass the accept headers:

https://iiif.io/api/cookbook/recipe/0057-publishing-v2-and-v3/manifest.json

[glenrobson]

Comments from the cookbook group:

• Could you add a link to your recipe from the index.md file? I think there is already the following heading which would be suitable Publishing v2 and v3 versions. You'll also have to add the link to the recipe in _includes/links.md.
• For the content could you use a IIIF Fixture image (https://fixtures.iiif.io)
• and a IIIF Image service. The structure for a version 3 image is:

https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen

and for a version 2 image:

https://iiif.io/api/image/2.1/example/reference/918ecd18c2592080851777620de9bcb5-gottingen

• Related recipes
  • Could you add a link to the Basic IIIF image (#0005 — Image Service for single image)

Finally a personal comment. The recipe is currently setup to proxy the correct version of the manifest but as discussed this make it very difficult for the average web user to access one of the manifest versions. One alternative solution is to redirect based on the accept header. In the recipe example this would mean:

https://iiif.io/api/cookbook/recipe/0057-publishing-v2-and-v3/manifest.json

could send a redirect to:

https://preview.iiif.io/cookbook/0057-conneg/recipe/0057-publishing-v2-and-v3/manifest-v3.json

and if you set the version 2 accept header it could redirect you to:

https://preview.iiif.io/cookbook/0057-conneg/recipe/0057-publishing-v2-and-v3/manifest-v2.json

This would have the advantage that version 3 and 2 can be viewed in a browser. One issue the IIIF Staff are having is that its difficult to share production version 3 manifests as they are hidden behind accept headers. With the redirect solution we could share a URL to a version 3 version.

It would be good to mention the redirect option in the recipe but with enough strong reasons to say why its not the preferred option to ensure the proxy method gains traction. (I personally lean to the redirect option but am willing to be persuaded its not the best course of action).

[ahankinson]

Thanks Glen -- I'll try to get to this in the next couple weeks.

Regarding redirects, the redirect solution is interesting, but it does present issues with the use of IDs. The IIIF spec says:

If the resource is retrievable via HTTP(S), then the URI MUST be the URI at which it is published.

So we can't keep the same URI with a redirect, since the ID would be different for each manifest. This will then break any sort of harvesting and annotation, since it's not just manifests but also canvases, etc. that would also need to be negotiated.

You could ALSO publish a direct link to the same document using "path negotiation" but I don't think that's a very scalable solution for a larger IIIF installation, since you would then be publishing multiple URIs for the same content, and you will run into the same problem that this is trying to address i.e., annotations on one set of URIs break when that version of IIIF is deprecated.

[triplingual]

Is the Content Negotiation in place currently? I get the same v3 manifest back using the curl line in the recipe, but perhaps that is expected behavior at this point.

[glenrobson]

Note we discussed this in the Internet Archive work here: https://github.com/ArchiveLabs/iiif.archivelab.org/issues/74