Follow Semantic Versioning about api HOT 27 CLOSED

This came up very briefly at our last meeting. We broke the SemVer semantics by dropping support for the /info.xml syntax between 1.0 and 1.1 (probably in other ways as well). We're doing it again between 1.1 and the next revision as IIIF has settled on a namespace and any dependency on the compliance level or @context URIs will break backwards compatibility.

I am interested in this idea and exploring it more. There would be a question of how to migrate to this method of naming from our current method. Three proposals for the image API:

1. Alias approach:
   • Version 1 is SemVer 1.0.0. URIs only need to contain a '1', not 1.x.x as this would break back compatibility, so I think we're OK there.
   • Version 1.1 is SemVer 2.0.0. Add 3xx aliases from URIs that contain '1.1' to URIs that replace it with a '2', or just make both URIs work.
   • Next version is 3.0.0, future work on auth isn't likely to break anything, so after that it's 3.1.0
   • Typo or HTML fixes, or clarification would increment the PATCH place.
2. Keep public name separate approach:
   • Keep incrementing as we are now, but publish a SemVer number as well, somewhere near the top of the spec. The SemVer number should still be the number we use in URIs, as explained above.
3. Just start, i.e. next revision is 2.0.0. I don't like this, but it is an option.

@azaroth42, @zimeon, @snydman: thoughts?

from api.

Really, we're 1.2 with the pixels API and (IMO) 2.1 with the subsidiary
information requests.

I understand the dependency management requirement, but the additions to me
don't seem like a new major version. I don't see any backwards
incompatibility in the Voodoo spec though. It seems like it would be 2.1
rather than 3.0. The URIs are always going to change, which would make the
semver pointless if that triggers a major version update.

Basically ... I think we stick to our current scheme as the changes in the
.json files are really minor changes -- they're extra information not the
main part of the API, which is the pixels.

On Mon, Mar 10, 2014 at 6:59 AM, Jon Stroop [email protected]:

This came up very briefly at our last meeting. We broke the SemVer
semantics by dropping support for the /info.xml syntax between 1.0 and
1.1 (probably in other ways as well). We're doing it again between 1.1 and
the next revision as IIIF has settled on a namespace and any dependency on
the compliance level or @context URIs will break backwards compatibility.

I am interested in this idea and exploring it more. There would be a
question of how to migrate to this method of naming from our current
method. Three proposals for the image API:

Alias approach:
- Version 1 is SemVer 1.0.0. URIs only need to contain a '1', not
1.x.x as this would break back compatibility, so I think we're OK there.
- Version 1.1 is SemVer 2.0.0. Add 3xx aliases from URIs that
contain '1.1' to URIs that replace it with a '2', or just make both URIs
work.
- Next version is 3.0.0, future work on auth isn't likely to break
anything, so after that it's 3.1.0
- Typo or HTML fixes, or clarification would increment the PATCH
place.
2.

Keep public name separate approach:
- Keep incrementing as we are now, but publish a SemVer number as
well, somewhere near the top of the spec. The SemVer number should still be
the number we use in URIs, as explained above.
3.

Just start, i.e. next revision is 2.0.0. I don't like this, but it is
an option.

@azaroth42 https://github.com/azaroth42, @zimeonhttps://github.com/zimeon,
@snydman https://github.com/snydman: thoughts?

Reply to this email directly or view it on GitHubhttps://github.com//issues/47#issuecomment-37184436
.

from api.

Actually, we're 1.0.2 with the pixels as the changes are just documentation
fixes.

R

On Mon, Mar 10, 2014 at 8:20 AM, Robert Sanderson [email protected]:

Really, we're 1.2 with the pixels API and (IMO) 2.1 with the subsidiary
information requests.

I understand the dependency management requirement, but the additions to
me don't seem like a new major version. I don't see any backwards
incompatibility in the Voodoo spec though. It seems like it would be 2.1
rather than 3.0. The URIs are always going to change, which would make the
semver pointless if that triggers a major version update.

Basically ... I think we stick to our current scheme as the changes in the
.json files are really minor changes -- they're extra information not the
main part of the API, which is the pixels.

On Mon, Mar 10, 2014 at 6:59 AM, Jon Stroop [email protected]:

This came up very briefly at our last meeting. We broke the SemVer
semantics by dropping support for the /info.xml syntax between 1.0 and
1.1 (probably in other ways as well). We're doing it again between 1.1 and
the next revision as IIIF has settled on a namespace and any dependency on
the compliance level or @context URIs will break backwards compatibility.

I am interested in this idea and exploring it more. There would be a
question of how to migrate to this method of naming from our current
method. Three proposals for the image API:

Alias approach:
- Version 1 is SemVer 1.0.0. URIs only need to contain a '1', not
1.x.x as this would break back compatibility, so I think we're OK there.
- Version 1.1 is SemVer 2.0.0. Add 3xx aliases from URIs that
contain '1.1' to URIs that replace it with a '2', or just make both URIs
work.
- Next version is 3.0.0, future work on auth isn't likely to break
anything, so after that it's 3.1.0
- Typo or HTML fixes, or clarification would increment the PATCH
place.
2.

Keep public name separate approach:
- Keep incrementing as we are now, but publish a SemVer number as
well, somewhere near the top of the spec. The SemVer number should still be
the number we use in URIs, as explained above.
3.

Just start, i.e. next revision is 2.0.0. I don't like this, but it is
an option.

@azaroth42 https://github.com/azaroth42, @zimeonhttps://github.com/zimeon,
@snydman https://github.com/snydman: thoughts?

Reply to this email directly or view it on GitHubhttps://github.com//issues/47#issuecomment-37184436
.

from api.

Sorry, what were the "pixels API" changes? Is this something that predates my involvement?

Right now if I see @context: "http://library.stanford.edu/iiif/image-api/1.1/context.json", I'm going to a set of assumptions about what that server can do. The version is baked into that URI which means if I didn't get that URI from a IIIF server, compatibility is broken.

Going forward, we've added the protocol key as an unchanging URI that servers can use as a hook, and then further examine the capabilities of the server based on response from dereferencing the capabilities URI. With that in place, I agree that the URIs changing does not matter (as long as you're following your nose, and not simply making assumptions based on the URI as a key).

So, going forward, I agree with you, but IMO we're at 3.0.0-alpha right now.

from api.

On Mon, Mar 10, 2014 at 9:21 AM, Jon Stroop [email protected]:

Sorry, what were the "pixels API" changes? Is this something that predates
my involvement?

Nothing over the wire, just documentation tweaks. For example the
clarifications about canonical URIs in the latest version, removing the
broken Auth paragraph, clarifying floating point percents and rotations,
etc.

Right now if I see @context: "
http://library.stanford.edu/iiif/image-api/1.1/context.json", I'm going
to a set of assumptions about what that server can do. The version is baked
into that URI which means if I didn't get that URI from a IIIF server,
compatibility is broken.

Yes, and we are always going to make a new context document for a new
version, making everything backwards incompatible, making everything a new
major version ... thereby defeating the point of any notion of semantic
versioning.

Going forward, we've added the protocol key as an unchanging URI that
servers can use as a hook, and then further examine the capabilities of the
server based on response from dereferencing the capabilities URI. With
that in place, I agree that the URIs changing does not matter (as long as
you're following your nose, and not simply making assumptions based on the
URI as a key).

It is certainly going to be better from now on, regardless of the exact
label we give to it. But @context and profile URIs will change every time,
thus it's technically backwards incompatible. As will any JSON-LD, or
likely any serialization of linked data, based API.

R

from api.

On 03/10/2014 12:28 PM, azaroth42 wrote:

On Mon, Mar 10, 2014 at 9:21 AM, Jon Stroop
[email protected]:

Sorry, what were the "pixels API" changes? Is this something that
predates my involvement?

Nothing over the wire, just documentation tweaks. For example the
clarifications about canonical URIs in the latest version, removing the
broken Auth paragraph, clarifying floating point percents and rotations,
etc.

Gotcha, OK.

Right now if I see @context: "
http://library.stanford.edu/iiif/image-api/1.1/context.json", I'm going
to a set of assumptions about what that server can do. The version
is baked
into that URI which means if I didn't get that URI from a IIIF server,
compatibility is broken.

Yes, and we are always going to make a new context document for a new
version, making everything backwards incompatible, making everything a new
major version ... thereby defeating the point of any notion of semantic
versioning.

What I proposed is that profile and context URIs only reflect the major
version, otherwise, yes, it's pointless.

Going forward, we've added the protocol key as an unchanging URI that
servers can use as a hook, and then further examine the capabilities
of the server based on response from dereferencing the capabilities URI. With
that in place, I agree that the URIs changing does not matter (as
long as you're following your nose, and not simply making assumptions based
on the URI as a key).
It is certainly going to be better from now on, regardless of the exact
label we give to it. But @context and profile URIs will change every time,
thus it's technically backwards incompatible. As will any JSON-LD, or
likely any serialization of linked data, based API.

Not if you're following the spec. The only contract the spec is making,
going forward, is that the protocol URI won't change. If you took a
shortcut and used the context or profile URI directly then it's your
client software that's broken, not backwards compatibility.

from api.

Sorry, one more addition. The other stable URI in the game here is the Base-URI for your image. Most of the practical linked data applications I can imagine (e.g. the relationship between the Metadata API and the Image API) would be dependent on that URI not changing; not the context or profile.

from api.

Very true.

On Mon, Mar 10, 2014 at 9:47 AM, Jon Stroop [email protected]:

Sorry, one more addition. The other stable URI in the game here is the
Base-URI for your image. Most of the practical linked data applications I
can imagine (e.g. the relationship between the Metadata API and the Image
API) would be dependent on that URI not changing; not the context or
profile.

Reply to this email directly or view it on GitHubhttps://github.com//issues/47#issuecomment-37204594
.

from api.

So, thoughts about the URIs only reflecting the major field in the SemVer revision number?

from api.

the URIs only reflecting the major field in the SemVer revision number

Yes. Fewer URLs are better. Look how Google fails on maintaining the Google Maps Javascript Reference. The deprecated version URL is broken (404).

• experimental version: /3.exp/reference
• release version (3.9): /reference
• deprecated version (3.8): /3.8/reference

Same approach in the Angular Reference, lot of 404s. This is bad.

The other stable URI in the game here is the Base-URI for your image. Most of the practical linked data applications I can imagine (e.g. the relationship between the Metadata API and the Image API) would be dependent on that URI not changing; not the context or profile.

Yes. You would simplify things, if the image and the meta API share the same version.

# current
api/
  |__ image/
    |__ spec/
    |__ compliance/
  |__ meta/
    |__ spec/
    |__ compliance/
# latest 1.x.y
api/
  |__ 1/
    |__ image/
      |__ spec/
      |__ compliance/
    |__ meta/
      |__ spec/
      |__ compliance/

from api.

Btw, the link

http://library.stanford.edu/iiif/image-api/1.1/context.json

is broken.

from api.

Is it considered broken if it never worked in the first place? 😿 See #2.

from api.

One more comment for versioning. Git allows branches in submodules. You can write the specs in this repository and just include the different branches in the website repository.

from api.

Concrete proposal from someone who cares, or close with wontfix ?

from api.

I submit #1 in my post way up the page as a proposal.

from api.

What are the URIs if there are two versions? It seems pointless to re-number a version to me.
I prefer option 3 (eg next version is 2.0.0) which also allows presentation API to synchronize to 2.0.0 at the same time.

However, that's not to say that the next version of presentation API isn't 3.0.0 while image api is 2.0.1 as there might be big changes to one and not to the other. Also search and annotation can't start at 2.0.0.

Unless there's a practical advantage to aliasing that I'm missing?

from api.

I'd support that (ie just start). And URIs only reflect the major version.

from api.

I agree that there is no benefit in renumbering/aliasing past versions. If we do this we just start.

Seems to me it makes sense only if we do it for all IIIF specs. I assume that is what is imagined?

from api.

All specs, individually, right? Eg the search API will start at 1.0.0, at the same time as the presentation and image APIs being at 2.X.Y

If the URIs only reflect the major version, what happens to the previous minor and patch version documents? They get moved to a different URI, but the latest version is always at major?
eg:
api/image/2/index.html (version 2.1.3)
api/image/2/2.1.2/index.html (previous version, 2.1.2)
api/image/2/2.1.1/index.html (previous previous version, ... you get the idea)

from api.

I think we stick to the major version in the URI for the latest and put the semver number somewhere somewhat prominent near the top of the spec. Once a version is no longer the latest we just use the full semver number (What's the thought behind the extra '2/' above?).

from api.

I agree that version numbers are specific to each spec. What I meant by "all IIIF specs" is that we should not apply this scheme to a subset (such as just image), I think we need to be consistent and do semantic versioning for all specs. This might mean that we should expand the number of people we consult to get buy-in from. There are some implications for PR here (e.g. desire to hide breaking changing behind non-semantic versioning).

I would think URIs would be like
api/image/2/index -> 302 to api/image/2.1.3/index
api/image/2.1.3/index
api/image/2.1.2/index
etc.

from api.

Shall we take it to IIIF-Discuss?

On Fri, Mar 21, 2014 at 9:17 AM, Simeon Warner [email protected]:

I agree that version numbers are specific to each spec. What I meant by
"all IIIF specs" is that we should not apply this scheme to a subset (such
as just image), I think we need to be consistent and do semantic versioning
for all specs. This might mean that we should expand the number of people
we consult to get buy-in from. There are some implications for PR here
(e.g. desire to hide breaking changing behind non-semantic versioning).

I would think URIs would be like
api/image/2/index -> 302 to api/image/2.1.3/index
api/image/2.1.3/index
api/image/2.1.2/index
etc.

Reply to this email directly or view it on GitHubhttps://github.com//issues/47#issuecomment-38286007
.

from api.

I'm not really sure that's necessary, but I do see @zimeon's point. What about bringing in @snydman first?

from api.

Sure. And Tom as well, I think.

On Fri, Mar 21, 2014 at 9:27 AM, Jon Stroop [email protected]:

I'm not really sure that's necessary, but I do see @zimeonhttps://github.com/zimeon's
point. What about bringing in @snydman https://github.com/snydmanfirst?

Reply to this email directly or view it on GitHubhttps://github.com//issues/47#issuecomment-38287088
.

from api.

Am writing it up (unless one of you has already started?)

from api.

Done.

from api.

For posterity, we added this section to the Image API: 1986464#diff-381a219298e27a83caa34173bf7eba82R523

from api.