search

ORCID / ORCID-Parent

Repository for the real ORCID code. Any issues with devsandbox.orcid.org should be logged here.
9 stars 0 forks source link

URL-based API versioning #13

Open gthorisson opened 12 years ago

gthorisson commented 12 years ago

This is perhaps already somewhere on the dev & roll-out roadmap: would adding explicit URL-based API versioning no be sensible, as a future-proofing measure?

I am aware that there is versioning support in the current sandbox release. From http://dev.orcid.org/docs/query-api:

curl -H "Accept: application/orcid+xml; version=1.1" "http://devsandbox.orcid.org/4444-4444-4444-4446/orcid-bio" -D - -L

But this is strictly format-based, if I understand correctly: the client is able to specifically requesting version 1.1 of the XML representation. What happens if/when the APIs as a whole (parameters, representations, etc.) changes enough that it is likely to break apps that rely on it?

Embedding API versioning info directly in the URLs is one way of dealing with this and would allow running old + new API versions side by side if need be. Couple of examples:

Tier 1: http://orcid.org/api/v1/search <-- current http://orcid.org/api/v2/search <-- future version which takes different paramters

Tier 2: http://api.orcid.org/v1/oauth/token http://api.orcid.org/v6.5/oauth/some_future_oauth vX_endpoint

gthorisson commented 12 years ago

Follow-up: if specifying the version in the URL is not desired / not-so-good practice, can the semantics of the Accept header then be altered to mean the version of the API rather than the version of the XML/JSON/etc. representation?