open-multinet/federation-am-api — pull request #47 by wvdemeer (2014-07-01 14:16:03+00:00)
Title: Proposal: Add RSpec version to Allocate

# Context:
The following calls return an RSpec:
- Allocate (manifest)
- Provision (manifest)
- Describe (manifest)
- ListResources (advertisement)

The following calls take an RSpec as argument:
- Allocate (request)

# Problem:
Allocate is the only one of the calls that returns an RSpec, but does not have the mandatory rspec_version argument that specifies in which format it needs to be returned. (It does not even have this argument as an option.)

Additionally, Allocate takes a request RSpec as mandatory parameter, but users cannot specify in which format this request RSpec is. So I guess the server needs to figure this out. This makes it harder for servers that supports multiple request RSpec formats: they needs to be able to determine the type of the RSpec. Assuming RSpecs are always XML, this might be easy (using the namespace), but that is perhaps not always a valid assumption?

# Solution:
I propose to add the rspec_version argument to Allocate, for both the argument RSpec and the return RSpec. Is this a good idea? Any feedback on this?

## Alternative solution
Note that AMv3 does not specify how the AM detects the request manifest type, but it does specify that the AM should reply with a manifest RSpec in the same format as the request RSpec. So another option is to specify only the request RSpec type, and return a manifest of the same RSpec type.

This probably isn't easier to implement however, as the AM is still required to translate the manifest RSpec if the client issues a Describe call and requests another format.

# How to change the API:
This issue contains a proposal on how to change the API to include both RSpec versions. This is meant to demonstrate how this could be done. It will be updated based on the result of discussing the above.

(If this proposal is a good idea, it might be added to the API in a cleaner way, so any feedback on that is also appreciated! For example, argument 3, the "struct rspec" now contains both the type, version and the rspec itself. Would it be better to split this up? Also, the manifest_rspec_type could also be an option instead of a mandatory argument, and when not specified, it could default to the same version as the request. )