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.
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”}
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="}'
If the Login Call is successful, you will receive a
200 OK
status response.
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..."
}
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'
If the Login call is successful, you will receive a
200 OK
status response.
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
Was this helpful?