open-multinet/federation-am-api — pull request #18 by wvdemeer (2014-05-13 09:05:44+00:00)
Title: Proposal: improve return when invalid slivers

Proposal for improved return of call in cases with expired, deleted or non existing slivers

Many methods take an urns argument, which is either a single slice URN, or a list of sliver URNs in a single slice. In AMv3, the allowed return value/error code was much too broad for such calls:
> Calling Status() on an unknown, deleted or expired sliver (by explicit URN) shall result in an error (e.g. SEARCHFAILED, EXPIRED or ERROR) (unless geni_best_effort is true, in which case the method may succeed, but return a geni_error for each sliver that failed). Attempting to get Status() for a slice (no slivers identified) with no current slivers at this aggregate may return an empty list for geni_slivers, may return a list of previous slivers that have since been deleted, or may even return an error (e.g. SEARCHFAILED or EXPIRED). Note therefore that geni_slivers may be an empty list.

I propose to simplify the return of calls that have an urns argument, giving a single simple consistent return for all these cases (except for best_effort. best_effort will probably be subject of another proposal).

Note that not all AM's will have info on expired on deleted slivers, so it is not a good idea to make the return make a difference for expired, deleted or non-existing slivers. These 3 cases should be the same in the return as some AM's will not be able to differentiate.

I think there are 3 options left:
* Either return an error (SEARCHFAILED is appropriate)
* Return SUCCESS but exclude the expired, unknown and deleted sliver(s) from the returned list of slivers
* Return SUCCESS and add all sliver(s), including expired, unknown and deleted slivers, to the return. Add an appropriate allocation_status ":unallocated" when needed. When urns contains a slice URN, an empty list of slivers needs to be given (unless the aggregate knows expired or deleted slivers).

I've chosen for the first option in this proposal. If another option is better, I will change the proposal.
Any thoughts?