Globus Subscription API suggestion

globus_sub_api.txt

This is a request for a completely new Globus API.  API credentials come from Globus Auth, but a new scope is used.

The idea behind this API is two-fold:

1. Allow the subscription to take place without having to pass credentials around.

2. Give Subscription Managers an easy way to list all the endpoints covered under a subscription, and see their details.

The last point is important: This API would give subscription managers access to endpoint details, even if the endpoint is marked private.

The overall flow is this: The endpoint owner (normally via command line) indicates that they want the endpoint to be managed.  A subscription manager (via web site or direct API call) then makes the endpoint managed.

Here are the calls I'd like the API to have:

• request: Indicate that an endpoint wants to be covered under a subscription.

Parameters:

- endpoint_id: The UUID of the endpoint that you want added to a subscription.
- subscription_id: The UUID of the subscription to which you want to add this endpoint, or a string (see below).
- migrate: Boolean.  Optional, defaults to false.  Set to true if the endpoint is already covered under a subscription, and the endpoint owner wants to move to a different subscription.
- force_downgrade: Boolean.  Optional, defaults to false.  Set to true (along with `migrate`) to allow an endpoint to be moved from a more-restrictive tier to a less-restrictive tier.

This API call is made by endpoint owners only.  This is how endpoint owners indicate that they want an endpoint to be covered under a subscription, and are accepting any terms & conditions that the subscription imposes.

If they know the subscription ID, they can provide it via the `subscription_id` parameter.  Otherwise, they can provide one of three special strings:

- “ANY” means they want to be covered under any subscription.  The first subscription manager to use the `bless` call on the endpoint will get it.
- “ANY HA” is similar to “ANY”, but is restricted to High Assurance and HIPAA BAA subscriptions.
- “ANY BAA” is similar to “ANY”, but is restricted to HIPAA BAA subscriptions. 

NOTE: If the caller is also a subscription manager, and wants to make the endpoint managed under their subscription, they may skip this call, and instead proceed directly to the `manage` call (see below).

Return Codes:

- 200: Either the request is successful, or the endpoint is already covered by the requested subscription.
- 401: You are not the owner of the endpoint (although, this could be an information leak).
- 404: Either the endpoint ID or the subscription ID does not exist.
- 409: Returned when trying to move an endpoint from a higher (or more-restricted) subscription tier to a lower tier, and ` force_downgrade` was not set to True.
- 422: The endpoint is already covered under a subscription, and the `migrate` parameter is not set to True.


• manage: Add an endpoint to a subscription.

Parameters:

- endpoint_id: The UUID of the endpoint that you want managed.
- subscription_id: The UUID of the subscription that should be associated with the endpoint.
- migrate: Boolean.  Optional, defaults to false.  Set to true if the endpoint is already covered under a subscription, and the subscription manager wants to move to a different subscription.
- force_downgrade: Boolean.  Optional, defaults to false.  Set to true (along with `migrate`) to allow an endpoint to be moved from a more-restrictive tier to a less-restrictive tier.

This API call is made by a subscription manager, and is used to add an endpoint to a subscription.  In order for the request to succeed, the endpoint owner must have already made a `request` call, either with a matching subscription_id or with an appropriate “ANY” string.

One exception to the above: If the caller is an endpoint owner _and_ a subscription manager, and the caller is adding their endpoint to a subscription they manage, then the `request` call may be skipped (though it does not have to be).  That essentially replicates the existing (GCSv4) endpoint-management functionality, where the owner of a managed endpoint is also a subscription manager.

If the endpoint in question is already covered under a subscription and the `migrate` flag is True, then the change of subscription will be atomic (so, for example, shared endpoints will not be interrupted). 

Return Codes:

- 200: Either the request is successful, or the endpoint is already covered by the requested subscription.
- 401: You are not a subscription manager, or are not the owner of the endpoint (although, this could be an information leak).
- 403: The endpoint owner has not yet submitted a `request` call to allow the subscription to take place.  Or, the endpoint owner specificed a different subscription ID.
- 404: Either the endpoint ID or the subscription ID does not exist.
- 409: Returned when trying to move an endpoint from a higher (or more-restricted) subscription tier to a lower tier, and ` force_downgrade` is not set to True.
- 422: The endpoint is already covered under a subscription, and the `migrate` parameter is not set to True.


• unmanage: Remove an endpoint from a subscription, or “take back” or reject a pending request.

Parameters:

- endpoint_id: The UUID of the endpoint that you want removed from the subscription.

This call makes an endpoint unmanaged.  A subscription manager may un-manage any endpoint covered by the subscription they manage.  Endpoint owners may also use this call to make their endpoint unmanaged (as an alternative to modifying the endpoint document using the Transfer API).

If an endpoint is not managed, but a request to be managed was made (using the `request` call), the endpoint owner may use this call to “take back” the request, and the subscription manager may use this call to “reject” an endpoint owner’s request.  Note however, that the “reject” case only works when the endpoint owner asked to be covered under a specific subscription.

Return Codes:

- 200: Either the request is successful, or the endpoint is not covered by a subscription.
- 401: You are not the owner of the endpoint, or a subscription manager (although, this could be an information leak).
- 404: The endpoint ID does not exist.


• list_endpoints: List endpoints covered under a subscription.

Parameters:

- subscription_id: The UUID of a subscription.
- show_requested: Boolean.  Optional, defaults to False.  When true, only return endpoints that have requested coverage under the provided `subscription_id`.

Used by subscription managers to view the endpoints covered under a subscription, or the endpoints that have asked to be covered under a subscription.

Note that endpoint documents returned via this call do not take the endpoint's 'public' flag into account.  In other words, this call will allow you (the subscription manager) to see the full detals of the endpoints covered under your subscription.  That is why this is a separate call from the existing call in the Transfer API.

Return Codes:

- 200: A successful request.  A list of endpoint documents is included.
- 401: You are not a subscription manager (although, this could be an information leak).
- 404: The subscription ID does not exist.


• list_subscriptions: List subscriptions.

No parameters.

This call may be used by any authenticated user to list the subscriptions they manage.

Return Codes:

- 200: A successful request.  A JSON list is returned.  Each list entry contains a subscription UUID, name/description, and tier (standard, HA, BAA, etc.).  The list may be empty.