[[PageOutline]]

= GENI Clearinghouse API =

'''WORK IN PROGRESS''': This API has not been standardized across control frameworks.

The GENI Clearinghouse API will define the operations that are available to an Aggregate Manager at a Clearinghouse.

This interface does not describe the API that a Researcher Client would use to communicate with a GENI Clearinghouse. For GENI Spiral 2, the API between Researcher Clients and Clearinghouses is specific to the Clearinghouse and not standardized.

See Also:
 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification]
 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture]
 * [http://www.protogeni.net/trac/protogeni/wiki/ClearingHouseAPI2 ProtoGENI Clearinghouse API revision 2]

-----
== !GetVersion ==
Return the version of the GENI Clearinghouse API supported by this clearinghouse.

{{{
struct GetVersion()
}}}

The result is a struct with at least the following members:

{{{
{
  int geni_api;
}
}}}

 `geni_api`::
    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The current version of the API is 1 (one).

Implementations can add additional members to the struct as desired. The prefix {{{geni_}}} is reserved for members that are part of this API specification. Implementation should choose an appropriate prefix to avoid conflicts.

This operation is similar to ProtoGENI's Clearinghouse [http://www.protogeni.net/trac/protogeni/wiki/ClearinghouseAPI2#GetVersion GetVersion] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.


-----
== Resolve ==
Lookup a URN and return information about the corresponding object.

{{{
struct Resolve(string urn)
}}}

 `urn`::
    The URN to be resolved.

Returns a struct with fields appropriate to the type of the object being resolved.

If the object being resolved is a slice, the returned struct should contain at least the following:

{{{
{
  geni_urn: <slice URN>;
  geni_creator: <user URN>;
}
}}}

 `geni_urn`::
    The URN of the slice being resolved as a string.

 `geni_creator`::
    The URN of the creator of the slice as a string.

If the object being resolved is a user, the returned struct should contain at least the following:

{{{
{
  geni_urn: <user URN>;
  geni_certificate: <X.509 certificate of user>;
}
}}}

 `geni_urn`::
    The URN of the slice being resolved as a string.

 `geni_certificate`::
    The certificate of the user as a base 64 encoded string.


This operation is similar to ProtoGENI's Clearinghouse [http://www.protogeni.net/trac/protogeni/wiki/ClearinghouseAPI2#Resolve Resolve] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s Resolve operation (sec. 6.1).