[[PageOutline]]

= GENI AM API Changes from version 2 to version 3 =

This page documents changes to the GENI Aggregate Manager API from [wiki:GAPI_AM_API_V2 version 2] to [wiki:GAPI_AM_API_V3 version 3]. It consists of the text describing the changes to the API which was used to define and adopt the changes to the API for version 3.
 * [wiki:GAPI_AM_API_V2 Version 2 of the GENI Aggregate Manager API]
 * [wiki:GAPI_AM_API_V3 Version 3 of the GENI Aggregate Manager API]
 * [wiki:GAPI_AM_API_DRAFT Draft changes to the GENI Aggregate Manager API] for future versions. That is where this text originally was written.

== Summary of Changes ==

This version of the AM API includes multiple changes since version 2 of the AM API. For experimenters, a few things are worth noting:
 - The old `CreateSliver` operation has now been broken into 3 steps:
  - `Allocate` to reserve the resources
  - `Provision` to instantiate the resources, which may take time to complete
  - `PerformOperationalAction(geni_start)` to start (e.g. boot) the resources, which also may take time to complete
 - Use the new intermediate `geni_allocated` state after `Allocate` to coordinate reservations across aggregates, e.g. to ensure another aggregate can give you nodes to be the other end of a requested link.
 - Multiple methods have been renamed, typically by removing the `Sliver` term from method names.
 - Sliver expiration is available in the return from multiple other methods, like `Provision`
 - You no longer use `ListResources` to see the contents of your slice - use `Describe` instead. `ListResources` is only for the AM's Ad RSpec.
 - Experimenters can select when to start or stop resources, e.g. when to boot a VM. Consult the operational state machine in the AM's Ad RSpec, and use `PerformOperationalAction`.
 - SSH login names and keys should be available in manifest RSpecs in a standard format.
 - Slice name restrictions have been codified and standardized.
   - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]+$'`

Tool developers should also be aware:
 - The `credentials` argument to methods is now a struct, including a type and version for each credential. AMs should advertise which credential types they accept. SAs should advertise which type they provide.
 - Aggregates may have their own operational states and actions. The Ad RSpec should define these, probably by `sliver_type`.

Listing of the Change Sets:
 - [#ChangeSetD:Sliver-specificoperations Change Set D: Slivers]: Change methods to clarify that there may be multiple slivers per slice at an AM, and to allow operating on individual slivers 
 - [#ChangeSetF3:SliverAllocationStatesandmethods Change Set F3]: Sliver Allocation States and methods
 - [#ChangeSetF4:SliverOperationsMethod Change Set F4]: Method to perform Sliver Operational actions
 - [#ChangeSetF5:SliverOperationalStates Change Set F5]: Sliver Operational States
 - [#Adopted:ChangeSetG:Credentialsaregeneralauthorizationtokens. Change Set G]: Generalize the credentials argument, allowing ABAC support
 - Change Set I1: !SliversStatus return structure includes sliver expiration
 - Change Set I2: !SliversStatus return includes SSH logins/key for nodes that support SSH access
 - Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration
 - [#Adopted:ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc.
  - Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates
  - Define slice ID as the UUID plus URN in slice certificates
  - Define slice name, sliver name, and user name restrictions, and similar for URNs
  - Publish schemas for credentials and certificates
 - [#ChangeSetM:NewMethodSignatures Change Set M]: New method signatures, incorporating all previous adopted change sets

'''FIXME''': Sub heading for each change set with a summary of the change set?

== Adopted Change Details ==

'''FIXME''': Sub heading for each change set with full text from the DRAFT page