Using a Service

You can use any service and its underlying HTTP API by subscribing to it with an application.

NOTE

Examples showing how to work with services (e.g., via Jupyter notebooks) can be found in the samples repository.

There are two ways to subscribe to a service. One is to subscribe to an internally published service, the other is to subscribe to a service that has been published on the marketplace.

Subscribe to an Internally Published Service

1. Navigate to the "Services" section from the main navigation and locate your service in the list.
2. Open the service details page and click on the "Publish Service" button and select "Internal" to make the service available within your account or organization.
3. Navigate to "Applications" from the main navigation to access your application overview.
4. Select the application you want to use to subscribe to the service and open its details page.
5. On the application details page, click the "Subscribe Internally" button.
6. A dialog box will appear prompting you to select the internally published service you want to subscribe to.
7. Choose the correct service from the list and click the "Subscribe" button in the dialog to complete the subscription.

Subscribe to a Service Published on the Kipu Quantum Hub Marketplace

1. Click on "Marketplace" in the top navigation bar or access https://hub.kipu-quantum.com directly.
2. Select "Browse all services" or directly click on one of the services offered by Kipu.
3. Browse through the service listings and select a service you want to subscribe to, then click on it to open its details page.
4. On the service details page, under "Pricing & Subscription" click the "Subscribe" button. This will open a subscription dialog.
5. In the dialog, select the application you want to use for this subscription from the dropdown menu and click the "Subscribe" button to confirm.

Note: You will only be able to subscribe to services with a "Free" or "Commercial" pricing plan. If a service is offered as "On Request", please reach out to the service provider for further assistance.

Obtain Service Gateway Credentials

After subscribing to a service with your application, you need to obtain the necessary credentials to interact with the service:

1. Navigate to "Applications" and select the application that subscribed to the service.
2. On the application details page, you will find the "Service Gateway Credentials" section containing:
   • Token Endpoint: The URL to request access tokens
   • Access Key ID: Your unique identifier for authentication
   • Secret Access Key: Your secret key for authentication (masked by default)

Request an Access Token

To authenticate your requests to the service, you need to obtain an access token using your Service Gateway Credentials:

1. On your application details page, locate the cURL command provided in the "Service Gateway Credentials" section.
2. The command is pre-configured with your Access Key ID and Secret Access Key encoded in Base64 format.
3. Copy the cURL command by clicking the copy icon next to it.
4. Execute the command in your terminal to request an access token:

curl -k -X POST https://gateway.hub.kipu-quantum.com/token -d "grant_type=client_credentials" -H "Authorization: Basic Base64(access-key-id:secret-access-key)"

The response will contain your access token:

{
  "access_token": "eyJ4NXQiOiJNell4TW1Ga09HWXdNV0kwWldObU5EY3hOR1l3WW1NNFpUQTNNV0kyTkRBelpHUX...",
  "scope": "default",
  "token_type": "Bearer",
  "expires_in": 3600
}

The access token is valid for the time specified in expires_in (in seconds). After expiration, you need to request a new token using the same cURL command.

Execute a Subscribed Service

To execute a service, you need to provide the following information:

1. Service Endpoint URL: Can be obtained from the subscriptions section of your application that subscribed to the service
2. Authorization Bearer Token: Obtained from the token endpoint using your Service Gateway Credentials as described above
3. Header Fields: Content-Type and Accept are both set to application/json
4. Provide input data according to the service's OpenAPI specification.

The following examples shows the cURL command and how to start a service execution:

curl -X 'POST' \
  'https://gateway.hub.kipu-quantum.com/70b6e720-dcec-4b9b-a462-a6fdaf400bfa/myservice/1.0.0/' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJ4NXQiOiJNell4TW1Ga09HWXdNV0kwWldObU5EY3hOR1l3WW1NNFpUQTNNV0kyTkRBelpHUXp...' \
  -d '{
    "data": {
      "values": [
        100,
        50,
      ]
    },
    "params": {
      "round_off": false
    }
  }'

For each call, a new service execution is created. The id of the service execution and its initial execution state is returned by the POST request. The POST above returns for instance the following result:

{
  "id": "02e0d85a-5a95-4abe-a642-1ee9a94fdf14",
  "status": "PENDING",
  "createdAt": "2022-09-19 16:45:24"
}

The execution id can be used to query the state and the result of a service execution.

Retrieve Execution Result

Since a service execution is performed asynchronously, you need to query its state to know if its execution completed. After a service was completed you can retrieve the result. Therefore, a service provides dedicated endpoints to query the state of each of its executions.

The state can be retrieved by calling the endpoint GET /{id}. The state of our example service execution with id 02e0d85a-5a95-4abe-a642-1ee9a94fdf14 can be for instance retrieved with the following request:

curl -X 'GET' \
  'https://gateway.hub.kipu-quantum.com/70b6e720-dcec-4b9b-a462-a6fdaf400bfa/myservice/1.0.0/02e0d85a-5a95-4abe-a642-1ee9a94fdf14' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ...'

If the execution is still running, you should get "status": "RUNNING" or "status": "PENDING". When the execution finished successfully, you should see "status": "SUCCEEDED". If you get either "status": "FAILED" or "status": "UNKNOWN" something went wrong.

You can retrieve the result or the cause of an error through the endpoint GET /{id}/result:

curl -X 'GET' \
  'https://gateway.hub.kipu-quantum.com/70b6e720-dcec-4b9b-a462-a6fdaf400bfa/myservice/1.0.0/02e0d85a-5a95-4abe-a642-1ee9a94fdf14/result' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ...'