Getting Started

Proton & the developer portal

Proton is the API middleware of IWG. It is composed of 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 this portal. Access approval is required, and products subscriptions are subject to approval.

Portal content

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

  • 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/%7Bid%7D[?mode])

  • Request parameters: Information about path, query and body parameters that endpoints use.

  • Request headers: Possible header names 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.

Sign up

To access and start using the developer portal, signing up to the portal is required:

  • https://protonuat.developer.azure-api.net/signup (AAD or form)

IWG Users can sign up with Azure Active Directory. Otherwise, basic registration is possible.

  • After signing up, the system sends a notification email to the user and IWG authorities.

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 approve the subscription if all prerequisites are satisfied.

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 via email or other channel and must 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

Some 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 clientId and clientSecret will 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.

API Usage

Endpoint URL Structure

The base URL to call Proton is:

Endpoint URLs are structured as:

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

such as, to query a specific location feature entity:

So, it can be called as:

GET https://api.proton-graph.cloud/public/sites/api/v2/locationFeatures/1?mode=Extended

Header details

These key-values should be considered in every request:

Common Proton Properties

These fields are common through all Proton entities:

Deferred Jobs

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 some endpoints, the API response will be a jobId with 202 Accepted, instead of an entity:

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.

End of the article.