[[PageOutline]]

= GENI Aggregate Manager API Outstanding Issues =

The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers. 

This page lists un-specified areas of the API, known problems, or gaps.

See Also:
 * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for the next version of this API
 * [wiki:GeniApi GENI API] implementation status
 * [wiki:GAPI_AM_API The latest API specification]

== Overall Issues ==
 1. Missing RSpec extension definition for specifying the operational states and methods supported by an aggregate / resource type
 2. No way to modify a reservation at an aggregate for a slice without deleting and recreating it
  * Proposal: See the [wiki:GAPI_AM_API_DRAFT UpdateSliver proposal]
 3. Tickets
  * Proposal: See the [wiki:GAPI_AM_API_DRAFT Tickets proposal]
 4. Define privileges required for each operation
  * But see the ABAC proposal and DRAFT proposal L
 5. Clarify use of error codes, possibly add more detailed codes
   * Proposal: Add more specific error codes for credential issues, specific bad argument cases
|| 18   || MISSINGARGS  || "Required argument(s) missing" || 
|| 19   || OUTOFRANGE   || "Requested expiration time or other argument not valid" || 
|| 20   || CREDENTIAL_INVALID   || "Not authorized: Supplied credential is invalid" || 
|| 21   || CREDENTIAL_EXPIRED   || "Not authorized: Supplied credential expired" || 
|| 22   || CREDENTIAL_MISMATCH   || "Not authorized: Supplied credential does not match the supplied client certificate or does not match the given slice URN" || 
|| 23   || CREDENTIAL_SIGNER_UNTRUSTED   || "Not authorized: Supplied credential not signed by trusted authority" || 
   * What error code should be used for a bad RSpec version requested or used? (In !ListResources and Allocate, be consistent)
    * 1=BADARGS, 4=BADVERSION, or 13=UNSUPPORTED? 4 seems appropriate, but maybe the semantics of BADVERSION are something else. PG does 1
     * Proposal: {{{BADVERSION}}}
   * What error code should be used for various 'nothing found' cases? (Be consistent across !ListResources, Delete, Status, Shutdown, Renew, etc.)
    * Use EXPIRED? SEARCHFAILED? Other?
    * There never was such a slice here
     * Proposal: Should be same as deleted.
    * That slice was here but expired
     * Proposal: {{{EXPIRED}}}
    * That slice was here but is empty
    * That slice was here but was deleted
     * Proposal: Should be same as 'was never here'.
    * That slice was here but was shutdown
 6. Should {{{am_type}}} and the RSpec {{{type}}} and prefixes for new options, etc be the same?
  * Should the RSpec {{{type}}} fields be the {{{am_type}}} values defined for return codes? 
   * Remove 'openflow' as unused here?
   * Should it be 'sfa' or 'planetlab'?
  * We say that implementations should name new options or returns to avoid naming conflicts. Should we specify that prefixes are registered? 
   * Should the prefixes be the {{{am_type}}} values
  * Proposal: Yes to all the above
 7. We do not define the semantics of supplying a list of credentials: are they additive to accumulate privileges? Or must 1 credential supply all needed privileges?
 
== !GetVersion Issues ==
 1. Are clients required to supply a valid/trusted certificate? IE must servers authenticate users? PL currently does not do this.

== !ListResources Issues ==
 1. Since v1 we have said that if there are no resources attached to this slice at the aggregate, an empty RSpec should be returned. Do all AMs do this?
  * Or should we change this to use an error code, more clearly distinguishing between errors, successfully reserving nothing, etc?
 2. PG uses BADARGS instead of BADVERSION. OK?
  * Proposal: Change to {{{BADVERSION}}}
 3. PG does not use BUSY, SERVERERROR, UNAVAILABLE, EXPIRED - OK?
  * Proposal: probably - up to them

== Describe Issues ==

== Delete Issues ==

== Status Issues ==
 1. Further specify what kinds of things go in specific {{{geni_resources}}} 
 2. Further specify what kinds of things this method might optionally additionally include and still be consistent with the intent

== Renew Issues ==
 2. Specify the error code if you try to renew past the life of your credential(s).
  * Proposal: Fails with {{{OUTOFRANGE}}}
 3. Specify the error code if there are no local resources in that slice

== Shutdown Issues ==
 1. What is the state of resources after this? Startable? Is there a procedure for this?
  * Proposal: Not restartable, not de-commissioned, not reservable, not accessible by the experimenters
  * See proposals for version 3