[OASIS Issue Tracker] Commented: (CAMP-40) version array resource/thing has a number of problems

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

    [ http://tools.oasis-open.org/issues/browse/CAMP-40?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=32708#action_32708 ] 

Adrian Otto commented on CAMP-40:
---------------------------------

> My main problem with Adrian's proposal is that the Endpoints resource and its
> referenced Endpoint resources are optional, yet Endpoint is the only place to 
> list "backwardCompatibleSpecificationVersions" and 
> "backwardCompatibleImplementationVersions". Since we are reducing 
> "specificationVersion" to a univalue String, these two arrays are the only 
> way for an older-version client to tell if a newer-version server is capable 
> of supporting it or not. This means that, even if I only provide a single 
> instance of a Platform resource, I can't up-rev my server version and still 
> support existing clients, unless I add support for Endpoints/Endpoint.

Yes, that restriction was intentional. I aimed to decouple version discovery from the Platform resource because:

1) Most providers probably want to allow version discovery in a way that is auth independent.
2) This particular information will change very rarely, and it would be nice to be able to give clients a clue that they can safely cache it for extended periods by offering a Cache-Control header with a long max-age value set. There is no clean way to do that on the Platform resource. It will need a relatively short TTL.
3) I wanted to stay as close to the CAMP-39 pattern as possible. If we treat version discovery differently than we handle discovery of other things, that may be a point of confusion with implementers.

> version array resource/thing has a number of problems
> -----------------------------------------------------
>
>                 Key: CAMP-40
>                 URL: http://tools.oasis-open.org/issues/browse/CAMP-40
>             Project: OASIS Cloud Application Management for Platforms (CAMP) TC
>          Issue Type: Bug
>          Components: Spec
>            Reporter: Gilbert Pilz
>            Assignee: Gilbert Pilz
>            Priority: Critical
>
> There are a couple of problems with the version array resource/thing defined in section 6.8.
> 1.) Unlike all the other things you can use HTTP GET to retrieve, the array of available versions is not defined as a first-class resource (i.e. it has no "type", "uri", "name", etc.) In the interests of simplicity it would be better if clients didn't have to special case the code that retrieves the version array.
> 2.) Placing the version array resource "under" the platform resource (i.e. at <platform-url>/api/versions) creates an inherent aliasing problem. For example, suppose a provider concurrently supported by CAMP 1.1 and CAMP 1.2. They might have a "Versions" resource that looked like the following:
> [
>   { "version" : "1.1", "href" : "http://camp.example.org/1.1";, "name" : "nCAMP 0.9 POC" },
>   { "version" : "1.2", "href" : "http://camp.example.org/1.2";, "name" : "BaseCAMP 1.0" }
> ]
> Should a client expect to be able to retrieve this resource through either "http://camp.example.org/1.1/api/versions"; or "http://camp.example.org/1.2/api/versions"; ? Should a client expect the representation of the resource at "http://camp.example.org/1.1/api/versions"; to be the same (baring any unexpected updates) as the representation of the resource at "http://camp.example.org/1.2/api/versions";? If we did decide to represent the version array as a first-class resource, what should the value of its "uri" attribute be?

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira