Proton

Proton is the API middleware of IWG. It is composed by a set of REST APIs. Authentication happens in two ways:

Authorization Key (mandatory)
Bearer Token (specific endpoints)

The access and the documentation (based on Swagger) are available in the web portal, for which is required to get access.

The access to Products is subjected to approval.

The Developer Portal

Proton Developer Portal consumers can find all required information about the APIs, including code snippets and samples. Registration is required.

The portal is organised as:

Products: Group of REST based APIs, defining the different journeys (e.g. Locations Journey)
APIs: Set of endpoints providing functionality (e.g. Locations)
Endpoints: Single functionalities within IWG universe, defined with HTTP-verbs (e.g. GET https://api.proton-graph.cloud/public/locations/api/v2/locationsFeatures/{id}[?mode])
Request parameters: Information about path, query and/or body parameters that endpoints use.
Request headers: Possible header names which are recognized by an endpoint. (e.g. Ocp-Apim-Subscription-Key)
Responses: Information about JSON representations of response models and possible status codes.
Code samples: Brief samples in various languages to call the API.

Signup

To access and start using the Developer Portal, signing up to the portal is required

Signup with AAD

IWG Users can sign up with Azure Active Directory. Non IWG users should contact proton@regus.com to request access to the API.

After signing up, a notification email is sent.

Subscribing to Products

Based on the type of access acquired by the registration a set of products is available, to which it is required to subscribe. IWG API Portal Admin will receive a notification and will approve the subscription if all prerequisites are satisfied.

A subscription is initiated by clicking on the Products menu and choosing one of the listed products and adding a subscription. If the subscription is subject to approval a message will be sent to the administrator with a request to enable your subscription.

Using your Subscription Key

Once the access is granted, two subscription keys for the product are delivered. It is also possible to regenerate the key in the Profile page if required. It is mandatory to consider this key as a secret not available outside of this context; it must not be shared by email or other channel and should be stored in a secure place.

IWG Admin can deactivate a key at any time if this is required.

The subscription key has to be passed within the Ocp-Apim-Subscription-Key header.

Bearer Token

Most endpoints require a second level of authorization from IWG Identity Server, and are restricted. The token can be obtained from Admin API, using Get token by identifier and secret endpoint, and consume it as JWT in the request headers.

Authorization: Bearer <yourToken>

Both clientIdand clientSecretwill be provided by Proton authorities. Again, it is expected to keep both values private in the application, and never share them with other parties.

Due to its nature, this token usually has a long lifespan and can be renewed. It is a recommended best practice to automatically renew the token based on its expired date and do not require a new token at each usage. It is good practice to have your system always provide this token on every request.

Endpoint URL Structure

The base URL to call Proton is:

https://api.proton-graph.cloud

Endpoint URLs are structured as:

{VERB} {baseUrl} + /public/ + {apiName} + /api/ + {version}/ + {entity} + /{param}[?mode]

such as, to query a specific location feature entity:

Required | Key                       | Value            | Source            | Notes
----------------------------------------------------------------------------------------------------------------------------------------
         | Accept-Language           | fr-FR            | Client            | Defaults to en-** if not provided
Required | Authorization             | Bearer <token>   | Supplied by Admin | Required for some endpoints, Best practice: include always
         | Content-Type              | application/json | Client            | JSON is the default
Required | Ocp-Apim-Subscription-Key | <api ket>        | Portal            | Required for accessing the API, Primary or Secondary

Common Properties

These fields are common through all Proton entities:

Id String: Although some identifiers can hold numeric or GUID values, this field is normalised to a string in Proton by design
ExternalReferenceIds array[string]: References of this entity in other systems
TimeStamp array[string]: Mandatory field to delete or modify an entity which was previously obtained to avoid 409 Conflict
Links array(string): links according to the HATEOAS specification
CreateDate DateTime: The date and the time this entity was created in Proton
IsDeleted boolean: Indicates if the entity has been removed from the system. When a delete operation is invoked Proton will mark the entity as deleted but the entity is not removed from system, it's a soft delete

Asynchronous operations

For operations with heavy calculations, Proton provides an asynchronous way of communication by using deferred jobs.

Below is the general workflow of deferred jobs in Proton:

For asynchronous endpoints, the API respond with 202 Accepted. In the response body a jobId is returned.

A jobId is a combination of date and a GUID.

{
  "jobId": "201907|19|bbe7e8af-bcca-442c-9150-2049058aba9a"
}

APIs contain Get Job Status endpoints, so this information can be queried.

{
  "jobId": "201907|19|bbe7e8af-bcca-442c-9150-2049058aba9a",
  "timestamp": "2019-07-19T13:40:54.8821367Z",
  "messageBody": "Command for 201907|19|bbe7e8af-bcca-442c-9150-2049058aba9a processing ce50ef5e-6757-4747-95f3-2b6dee416236: Succeed",
  "correlatedEntityId": "ce50ef5e-6757-4747-95f3-2b6dee416236",
  "status": "Completed"
}

messageBody field can contain additional information about the status like an error message.
correlatedEntityId is the identifier coming out from the relevant operation. These can be queried in their respective GET endpoints. (Confirm Inventory Reservation --> Get InventoryReservationConfirmation by Id)
status can be helpful to display a loading animation in a client application while it is not Completed.