Consuming an API (technical Implementation)

For API plans, with the information you find in the Subscriptions section, you can start implementing the necessary API calls in your application.

Use an API tool like Postman or cURL-commands to try them out or to run a quick test.

The URL in the API calls must always include the https:// prefix, otherwise the API call will return a 404.

Consuming a Service

To consume a service via the apinity marketplace, you need to have a Consumer Client for the authentication of your requests (Please refer to Consumer Clients for more information).

The first necessary step for the usage of every Service is the authentication to the API gateway. The gateway handles the authentication to the service provider automatically.

The service provider may require additional authorization. In such case, API requests must carry two authorization tokens (one for the marketplace, and one for the provider). For more info, see the concept article about Authorization.

Depending on the authentication type, the connection can be established as described below.

Connecting with API Key

Necessary for implementation are these two values:

  • Endpoint URL: The Endpoint URL is the base URL for implementing every API Call. This is found in the Technical Setup of every subscribed API service under Subscriptions.

  • API Key: The key is generated while creating a consumer client, and can’t be retrieved again after the consumer client has been saved. If you misplace it, you will need to generate a new key or create a new consumer client.

Step 1: Login Call

The first necessary API call is the Login needed for authentication against the apinity marketplace.

For this, use a POST to https://api.marketplace.apinity.io/{EndpointURI}/login with the following body as raw JSON request:

{"api-key": “API_KEY”}

The key name in this JSON is always api-key, not the name of the consumer client.

Example cURL:

curl --location --request POST 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/login' \
--header 'Content-Type: application/json' \
--data-raw '{"api-key": "d2tzZW9rNmE5aGF4djNjYWVtZDhzb2hyNmZnZTpeWWdTdzJHRDNhI3BRRFVHT29jaF9tUjdkJHY="}'

Step 2: Extract access token from Login response

In the response of this call, you will find the following information:

  • "expires_in": “expirationValue” – Expiration time of the token in seconds

  • "access_token": "accessToken” – The authorization token

Example Response:

{
    "expires_in": 31536000,
    "access_token": "Basic dnRsNnFpZXRqZG..."
}

The access token has a lifetime of exactly one year. Subsequent login calls within this period will return the same token. After expiry, a new login call is required.

Ending a subscription also invalidates the token as soon as the subscription expires.

Step 3: All further calls - input Authorization header in every header

Now you are ready to implement all further calls specified in the Swagger documentation by the service provider. For all these calls, these authorization values you received from the Login call should be sent as headers:

  • x-apx-authorization: “accesstoken" (required)

  • authorization: “providersAuthKey" (optional)

Example cURL

curl --location --request GET 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/v0/hello' \
--header 'x-apx-authorization: Basic dnRsNnFpZXRqZG...' \
--header 'Content-Type: application/json'

Connecting with OAuth2

Necessary for implementation are these three values:

  • Endpoint URL: The Endpoint URL is the base URL for implementing every API call. This is found in the Technical Setup of every subscribed API service under Subscriptions.

  • Client Id: This is generated together with the consumer client and is necessary for Authentication. You can look it up by clicking “edit” on the respective consumer client in the Consumer Clients section.

  • Client Secret: The secret is generated together with the consumer client and can’t be retrieved again after the consumer client has been saved. If you misplace it, you will need to generate a new secret or create a new consumer client.

Step 1: Login Call

The first necessary API call is the Login needed for authentication against the apinity marketplace.

For this, use a POST to https://api.marketplace.apinity.io/{EndpointURI}/login with the following body as x-www-form-urlencoded request:

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'

Example cURL:

curl --location --request POST 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=7ajv2oqbzerjln2ydlf0j9raasmo' \
--data-urlencode 'client_secret=Y1NuQGpMKmFHeXhuN1FtSUJ2XjdDM0smRUlj' \
--data-urlencode 'grant_type=client_credentials'

Step 2: Extract access token from Login response

In the response of this call, you will find the following information:

  • "expires_in": expirationValue – Expiration time of the OAuth token in seconds

  • "refresh_token_expires_in": refreshTokenExpiration – Expiration time of the OAuth refresh token in seconds

  • "access_token": "accessToken” The authorization token

  • "refresh_token": "refreshToken" – The refresh token

Example Response:

{
	"expires_in":300,
	"refresh_token_expires_in":1800
	"access_token":"Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiNWdkTlRfYmZzSmVLUHhiUklQRGUzQnF5NWRQREU1REZfejZ4djVkdzFnIn0.eyJleHAiOjE2NzA0MTI4ODAsImlhdCI6MTY3MDQxMjU4MCwianRpIjoiNWEwOWQxM2YtYWUxMi00YmI4LThjZDUtNjdjOWNiYzEyYjRhIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vYXV0aC9yZWFsbXMvc3luY2llci1tYXJrZXRwbGFjZS1lbmdpbmUiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZDBiNmU4NGEtY2YwYi00ZThiLTkzOTMtZjE3NjI1OTlhYTUzIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoibWFya2V0cGxhY2UtZ2F0ZWtlZXBlciIsInNlc3Npb25fc3RhdGUiOiIxMmVkOWQ1NS01MTM1LTQzZWUtOTMxZC1iYjY3NWFkNWUyOWYiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbmdpbmUtdXNlcm5hbWUiOiJha28xbGV0a254OGN3Mm44bmFzYTRjdmF6aHN0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInBhcnRuZXItbmFtZSI6IkJhbGF6cyBDUyBUZXN0IiwiZW5naW5lLXBhc3N3b3JkIjoicWU1RlZVYTRMUHExIW5aKEx3aypLYnh5VCNKIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiN2FqdjJvcWJ6ZXJqbG4yeWRsZjBqOXJhYXNtbyIsImVuZ2luZS1hdXRoLXR5cGUiOiJPQVVUSDIifQ.C6GAeFj2mY5r72jCF_Ejkqwb5Q5bWjoCDgng4C6yBtPzBXpLxQM95vNUoqXbsQ2YnyZ811ty_9RvDENAATOzy7euhvypnf1lkWypbQHPWDusGFs52Yf6JTwvJXcLJD7s-6TC-0poDP1t4CTaeS0S5l9poTopDrbel0BMjONOGEx5VK5FiRNxvVchK_6fWkyP_7wQVxLKNqA2xHSjtY8wWcsIOWYRwQYPV2t_UY9pAd8ALw_WeZZo5aXV7IllxeU0JUfB3litYYiWFxrfiU7kYDXCysTyl55L_7f1sClfJzLqr4QuaeHBZpzQutJ3VZrHYxozU6J9J1LgmVaUKjEv7Q",
	"refresh_token":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5MGU2YWU5MS01YTRjLTQyZWEtOGZhNy03OTgyMDc2ZTEwYTIifQ.eyJleHAiOjE2NzA0MTQzODAsImlhdCI6MTY3MDQxMjU4MCwianRpIjoiMTkxZDRlOTEtMGQ2YS00YWI2LThhOTgtZjVkNTVhYzcxMjFlIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vYXV0aC9yZWFsbXMvc3luY2llci1tYXJrZXRwbGFjZS1lbmdpbmUiLCJhdWQiOiJodHRwczovL2F1dGguYXBpbml0eS5pby9hdXRoL3JlYWxtcy9zeW5jaWVyLW1hcmtldHBsYWNlLWVuZ2luZSIsInN1YiI6ImQwYjZlODRhLWNmMGItNGU4Yi05MzkzLWYxNzYyNTk5YWE1MyIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJtYXJrZXRwbGFjZS1nYXRla2VlcGVyIiwic2Vzc2lvbl9zdGF0ZSI6IjEyZWQ5ZDU1LTUxMzUtNDNlZS05MzFkLWJiNjc1YWQ1ZTI5ZiIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.-GgqDoi956DZAIENvIwBmy7cZad7IlAYcfm5xrHbKJs"
}

Step 3: All further calls - input Authorization header in every header

Now you are ready to implement all further calls specified in the Swagger documentation by the service provider. For all these calls, the authorization information you received should be sent as headers:

  • x-apx-authorization: “bearerToken" (required)

  • authorization: “providersAuthKey" (optional)

Example cURL

curl -v --location --request GET 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/v0/hello' \
--header 'x-apx-authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiNWdkTlRfYmZzSmVLUHhiUklQRGUzQnF5NWRQREU1REZfejZ4djVkdzFnIn0.eyJleHAiOjE2NzkwNjAyNTQsImlhdCI6MTY3OTA1OTk1NCwianRpIjoiMGU5OTZmNmEtYWM4NS00ZGRmLWE4OTEtMGFmMTM3ODgxMjgyIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vcmVhbG1zL3N5bmNpZXItbWFya2V0cGxhY2UtZW5naW5lIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImQwYjZlODRhLWNmMGItNGU4Yi05MzkzLWYxNzYyNTk5YWE1MyIsInR5cCI6IkJlYXJlciIsImF6cCI6Im1hcmtldHBsYWNlLWdhdGVrZWVwZXIiLCJzZXNzaW9uX3N0YXRlIjoiMTFmNDhjOTgtODhkNC00ODg3LThiMDYtM2M2ZTQ1NDNjMmZjIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJzaWQiOiIxMWY0OGM5OC04OGQ0LTQ4ODctOGIwNi0zYzZlNDU0M2MyZmMiLCJlbmdpbmUtdXNlcm5hbWUiOiJha28xbGV0a254OGN3Mm44bmFzYTRjdmF6aHN0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInBhcnRuZXItbmFtZSI6IkJhbGF6cyBDUyBUZXN0IiwiZW5naW5lLXBhc3N3b3JkIjoicWU1RlZVYTRMUHExIW5aKEx3aypLYnh5VCNKIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiN2FqdjJvcWJ6ZXJqbG4yeWRsZjBqOXJhYXNtbyIsImVuZ2luZS1hdXRoLXR5cGUiOiJPQVVUSDIifQ.bO67OyNubiJHKWXeZ_VDh4a0pZZ0eep0V1uFssZP6nYyssZfH_qg6ed1jrgCl-heMQ7EyzoN4UuQlxXKXV_-N6g-ExhtMyDOIYpm9Hy6_DAF3-1AUM1mhodS38xwPA-H2eco5k8VqJTf5L99cpTuCvVGGg5wWvHEv5MlPOj_MpCrA8AvdhR6l2g4Pfjeh186k9qHFW0cwYTL54SDZX2iJOyCLiX0o0qyA6_jM3HKn_9m3MLGPyCNqDCqFTdOcbFkRGDlkd5Ib-6c-MkOb0CVa7AMtNW4_87a7dc_elnTj0_fzUVEVqOb1RMFT9eufkQgBzUdRe9Icb3EUaDT6RkfCg' \
--data-raw ''

Refreshing an expired OAuth2 Token

The OAuth2 tokens used by the marketplace expire after a while (time in seconds is specified in the /token endpoint response) and need to be refreshed by using the refresh token. Refreshing the token works by sending another POST request to the same endpoint:

URL: https://api.marketplace.apinity.io/{EndpointURI}/login

Method: POST

Content Type: application/x-www-form-urlencoded

Form Data:

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=Bearer ...' \

This request will return a response with a new access token and refresh token:

{
    "access_token": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiNWdkTlRfYmZzSmVLUHhiUklQRGUzQnF5NWRQREU1REZfejZ4djVkdzFnIn0.eyJleHAiOjE2NzA0MTMyOTAsImlhdCI6MTY3MDQxMjk5MCwianRpIjoiNGM0ZDBjZDctMDBhNC00NjdjLWI4NGYtMTRlZWYwNmFkZTM4IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vYXV0aC9yZWFsbXMvc3luY2llci1tYXJrZXRwbGFjZS1lbmdpbmUiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZDBiNmU4NGEtY2YwYi00ZThiLTkzOTMtZjE3NjI1OTlhYTUzIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoibWFya2V0cGxhY2UtZ2F0ZWtlZXBlciIsInNlc3Npb25fc3RhdGUiOiIxMmVkOWQ1NS01MTM1LTQzZWUtOTMxZC1iYjY3NWFkNWUyOWYiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbmdpbmUtdXNlcm5hbWUiOiJha28xbGV0a254OGN3Mm44bmFzYTRjdmF6aHN0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInBhcnRuZXItbmFtZSI6IkJhbGF6cyBDUyBUZXN0IiwiZW5naW5lLXBhc3N3b3JkIjoicWU1RlZVYTRMUHExIW5aKEx3aypLYnh5VCNKIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiN2FqdjJvcWJ6ZXJqbG4yeWRsZjBqOXJhYXNtbyIsImVuZ2luZS1hdXRoLXR5cGUiOiJPQVVUSDIifQ.G2Gx9sPgOsgXVtkBJ68f8U2VgV8FYXlMN0nUlF4eL_SohRtqrXq3yCzm0HD8xjAIBn6JyanqPf3RRemlkCl1mR_45jdspGZwe6rx1NB_LfktKDGYEpuj8bDuLYbnyqXZEUK-KA5LvfbUU3Ys69Fhl7pLqSenRLZelhL_ysVU0lMXonPkoGNRu4wTSqafF3tky4DC5lMwZ-qBfGnAIdi6MmEwFxQe2PlNquvtaCoueA5jVdtknXD75Gq8UL1zRNCtJ8o8LYvgI3dWt-e4URCLl7YpiCnTmdqxn0hOXQQM5c9mA6VXi-elKKcqT15bB0cR_QpOjBV7FjOwDlOC5SpL5g",
    "refresh_token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5MGU2YWU5MS01YTRjLTQyZWEtOGZhNy03OTgyMDc2ZTEwYTIifQ.eyJleHAiOjE2NzA0MTQ3OTAsImlhdCI6MTY3MDQxMjk5MCwianRpIjoiNjM2M2Q1OTMtNmNlMS00ZWY0LTgyMzUtYWI4NjM0Y2QxZGVkIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vYXV0aC9yZWFsbXMvc3luY2llci1tYXJrZXRwbGFjZS1lbmdpbmUiLCJhdWQiOiJodHRwczovL2F1dGguYXBpbml0eS5pby9hdXRoL3JlYWxtcy9zeW5jaWVyLW1hcmtldHBsYWNlLWVuZ2luZSIsInN1YiI6ImQwYjZlODRhLWNmMGItNGU4Yi05MzkzLWYxNzYyNTk5YWE1MyIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJtYXJrZXRwbGFjZS1nYXRla2VlcGVyIiwic2Vzc2lvbl9zdGF0ZSI6IjEyZWQ5ZDU1LTUxMzUtNDNlZS05MzFkLWJiNjc1YWQ1ZTI5ZiIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.yEST66fJA0SSkl6mqHKVu9wsxk_I7asx1LkELxVuWfs",
    "refresh_token_expires_in": 1800,
    "expires_in": 300
}

Testing a Service

Performance Test

For performance testing, we offer two helpful pieces of information in the response header of every call:

  • X-Kong-Upstream-Latency: Value in ms

This value shows how long the service provider takes to handle the API call (*1).

  • X-Kong-Proxy-Latency: Value in ms

This value shows how long the marketplace engine / API Gateway takes to handle the API call (*2).

Last updated