Overview
No subtopics in thissection
API providers have the privileges to publish and manage APIs in Developer Portal. You can add and manage providers using the Manage providers section.
Developer Portal sends notifications to API providers regarding any event for an associated API, like a token request, through the callback URL of the provider.
The providers added to Developer Portal can publish their APIs to their consumers. When you configure a Developer Portal destination in an API Gateway instance, the corresponding API Gateway instance is added as a provider in Developer Portal.
How do I create a provider?
No subtopics in thissection
This use case starts when you want to create a provider and ends when you have successfully created one.
In this example, consider creating a provider provider1 with the pet_v1 and pet_v2 APIs, and the http://api-dev.xyz.com/rest/apigateway/accesstokens callback URL.
Before you begin:
Ensure that you have the API Administrator privilege.
To create a provider
Click the user menu icon from the title bar and click Manage providers.
Click Create provider.
Provide Provider1 in the Name field.
Select the pet_v1 and pet_v2 APIs from the APIs field.
Select the http://api-dev.xyz.com/rest/apigateway/accesstokens callback URL from the Callback URLs field.
APIs that are not associated with a provider are displayed for selection because the assets associated with a provider cannot be associated with other providers.
Click Save.
The new provider appears in the API providers page.
How do I map an API or a callback URL to a provider?
No subtopics in thissection
When an API Gateway user publishes an API, the corresponding instance is added as a provider automatically. You can edit the provider to map the required APIs and callback URLs to the provider.
This use case begins when you want to edit a provider and ends after you successfully save your changes.
In this example, consider mapping the pet_v3 API to provider1.
To map an API or a callback URL to a provider
Click the user menu icon from the title bar and click Manage providers.
Click the edit icon next to the provider, provider1.
click Add in the API section.
Select pet_v3 from Add APIs.
Click Save.
Your changes are saved. The pet_v3 API is mapped to provider1. The provider can now manage the assets assigned to them.
Alternative steps:
- To edit provider details, click provider name from the Manage providers page and click Edit from the provider details page that appears.
Next steps:
- The providers can now manage the APIs assigned to them.
Third-party API Gateway Configuration
Integrating Third-party Gateway with Developer PortalCreating and Attaching WebhookPublishing APIs from Third-party Gateway to Developer PortalRequesting Application for Third-party Gateway APIsPublishing API analytics to Developer PortalYou can integrate third-party gateways with Developer Portal to allow them publish their APIs to Developer Portal. You can add the third-party provider details in Developer Portal and establish communication between the two using webhooks. The registered third-party providers can also publish API analytics to Developer Portal.
The high-level workflow is:
Integrating Third-party Gateway with Developer Portal
You must provide the third-party gateway details and add it as a provider to integrate the gateway with Developer Portal.
To integrate third-party gateway with Developer Portal
Add the third-party gateway as an API provider using one of these methods:
Make a REST call to the following endpoint:
POST /rest/v1/providers
Sample request
{ "name": "X Gateway", "shortDescription": "External Gateway", "description": "External Gateway", "version": "10.15", "external_key_provider": true }
Sample response
{ "id": "7ecefe01-efc7-43e4-9a19-57c3a761e252", "_self": "/portal/rest/v1/providers/7ecefe01-efc7-43e4-9a19-57c3a761e252" }
For information about the Providers REST API, see Managing providers.
Create provider from the Manage providers page of Developer Portal UI. For detailed information about adding a provider using UI, see How do I create a provider?
Next steps:
- Create and attach webhook to enable communication between the gateway and Developer Portal. Later, you can publish APIs from the registered gateway. For more information, see Creating and Attaching Webhook.
Creating and Attaching Webhook
After you specify third-party gateway details in Developer Portal, you must configure a webhook to enable communication between the two. Developer Portal uses the webhook to communicate with the gateway during the following events:
Gateway application creation
Gateway application scope increase
Gateway application scope decrease
Gateway application update
To create and attach webhooks
Create a webhook for the specified events by making a REST call to the following endpoint:
POST /rest/v1/hooks
Sample request
{ "url": "https://hookbin.com/NOjmeDg6o0ue8mNN8PxR", "configuration_type": "PROVIDER", "subscriptions": [ { "id": "GATEWAY_APPLICATION_CREATION_REQUEST_EVENT" }, { "id": "GATEWAY_APPLICATION_SCOPE_INCREASE_REQUEST_EVENT" }, { "id": "GATEWAY_APPLICATION_SCOPE_DECREASE_REQUEST_EVENT" }, { "id": "GATEWAY_APPLICATION_UPDATION_REQUEST_EVENT" } ] }
Sample response
{ "id": "07522ff8-fccd-45a0-b934-0ab67dffdf86", "_self": "/portal/rest/v1/hooks/07522ff8-fccd-45a0-b934-0ab67dffdf86" }
For information about using the Hooks REST API, see Managing webhooks.
You can also create webhooks using the Developer Portal UI. For information about creating webhooks using UI, see How do I configure webhooks to notify events to an external system?
Specify the provider Id in Developer Portal by making a REST call to the following endpoint:
PUT /rest/v1/providers/id
Sample request
PUT /portal/rest/v1/providers/cf864096-75c9-4d46-8002-923d8ebbcd67 { "name": "X Gateway", "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4", "id": "cf864096-75c9-4d46-8002-923d8ebbcd67", "providerRef": "cf864096-75c9-4d46-8002-923d8ebbcd67", "stage": "X Gateway", "type": "THIRD_PARTY", "summary": "External Gateway", "description": "External Gateway", "webhooks": [ "07522ff8-fccd-45a0-b934-0ab67dffdf86" ] }
Sample response
{ "name": "X Gateway", "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4", "id": "cf864096-75c9-4d46-8002-923d8ebbcd67", "documentType": "PROVIDER", "providerRef": "cf864096-75c9-4d46-8002-923d8ebbcd67", "stage": "X Gateway", "webhooks": [ "07522ff8-fccd-45a0-b934-0ab67dffdf86" ], "type": "THIRD_PARTY", "summary": "External Gateway", "description": "External Gateway" }
Next steps:
- Publish APIs for the gateway that you registered with Developer Portal. For more information, see Publishing APIs from Third-party Gateway to Developer Portal.
Publishing APIs from Third-party Gateway to Developer Portal
You can publish SOAP or REST APIs for the registered gateways to Developer Portal using any of these specifications - File, URL, or content.
To publish APIs from third-party gateway to Developer Portal
Publish APIs using any of the following methods:
Make a REST call to the following endpoint:
POST /rest/v1/apis
Sample request
POST /rest/v1/apis HTTP/1.1 Host: localhost:18151 Authorization: Basic QWRtaW5pc3RyYXRvcjpQQHNzdzByZEAxMg== Content-Length: 564 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="url" https://petstore.swagger.io/v2/swagger.json ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="type" swagger ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="async" false ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="providerid" cf864096-75c9-4d46-8002-923d8ebbcd67 ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="name" petstore1 ----WebKitFormBoundary7MA4YWxkTrZu0gW
Sample response
{ "id": "842c3e33-5c4b-4abf-b827-1a194affde50", "_self": "/portal/rest/v1/apis/842c3e33-5c4b-4abf-b827-1a194affde50" }
For information about the Providers REST API, see Managing Providers.
- Publish APIs through the Developer Portal UI. For detailed information about publishing APIs, see How do I create an API?
Next steps:
View the published API from the API gallery page and the Manage APIs page.
Request access tokens or application to invoke APIs published from third-party gateway. For more information, see Requesting Application for Third-party Gateway APIs.
Requesting Application for Third-party Gateway APIs
When you request for an application to access an API from a third-party gateway, the webhook attached to the gateway communicates the request to the gateway as an event payload.
The gateway then creates API key, JWT, or OAuth access token for the requested API. You can then update the access token credentials in Developer Portal.
The following diagram shows the basic flow of the application approval process:
To request application from third-party gateway:
Request for application to test an API using one of these methods:
Make a REST call to the following endpoint:
POST /rest/v1/requests
For example, the following request creates an app Petstore App for invoking the API petstore1
{ "context": { "name": "Petstore App", "description": "This application is used for building petstore app", "apis": [ "842c3e33-5c4b-4abf-b827-1a194affde50" ] }, "type": "APPLICATION_CREATION_REQUEST" }
Sample response
{ "id": "15fe0192-24e4-422a-afa5-58879161b9dc", "_self": "/portal/rest/v1/requests/15fe0192-24e4-422a-afa5-58879161b9dc" }
Sample webhook payload sent to the callback URL of the third-party gateway
{ "executor": { "id": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4", "email": null, "lastname": "System", "firstname": "Administrator", "name": "administrator" }, "source": { "id": "842c3e33-5c4b-4abf-b827-1a194affde50", "externalref": "24372f80-072e-455f-9235-5c01fbe6f139" }, "contextdata": { "consumer_appName": "Petstore App", "consumer_appDesc": "This application is used for building petstore app", "tenant": "default", "redirect_uris": [ "https://hostname:18152/portal/rest/v1/oauth/callback" ], "provider_id": null, "api_id": "842c3e33-5c4b-4abf-b827-1a194affde50", "application_id": "6179b933-1382-4e1a-becc-239dcfeaaa6d" }, "type": "REQUEST_ACCESS_TOKEN", "creationdate": "2022-01-10 14:36:14", "eventid": "5790ab9a-5312-4122-8aa8-8ca21cf98663", "status": "NEW" }
- Request for an application through Developer Portal UI. For detailed information about creating an application request, see Creating an application.
Update the access token credentials (API Key, OAuth, and JWT) in Developer Portal by making REST call to:
PUT /rest/v1/applications/{id}?eventId=${eventId}
For example, this request updates the access token required to access the API, petstore1.
PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=5790ab9a-5312-4122-8aa8-8ca21cf98663 { "name": "Petstore App", "credentials": [ { "expiry": null, "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844", "type": "APIKey" }, { "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53", "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86", "scopes": [], "tokenLifeTime": 3600, "tokenRefreshLimit": 0, "authorizationUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize" ], "accessTokenUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken" ], "redirectUris": [ "https://hostname:18152/portal/rest/v1/oauth/callback" ], "refreshTokenUris": [ "https://hostname:5543/invoke/pub.oauth/refreshAccessToken" ], "type": "OAuth2" }, { "claimsets": [ { "name": "JWT default claims set", "claims": [ { "key": "app_id", "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a" } ] } ], "accesstoken_uris": null, "type": "JWT" } ] }
Sample response
{
"code": 200,
"message": "Application is updated successfully"
}
Next steps:
You can share the access tokens generated for an API to other APIs by increasing the scope of the application.
You must raise a request to the third-party gateway to add the new API details to an existing application. The gateway then updates the application, generates a new access token, and sends the token to Developer Portal.
The following example describes how to add an API, petstore2, to the previously created application, Petstore App.
Make a REST call to the following endpoint:
POST /rest/v1/requests
Sample request
POST /rest/v1/requests { "context": { "application": "6179b933-1382-4e1a-becc-239dcfeaaa6d", "apis": [ "717eaf03-3c59-448e-8acb-7f3a52667932" ] }, "type": "APPLICATION_API_REGISTRATION_REQUEST" }
Sample webhook payload sent to the third-party gateway
PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=ebdcef36-1bf6-4998-9556-9fa38b3785b9 { "name": "Petstore App", "credentials": [ { "expiry": null, "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844", "type": "APIKey" }, { "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53", "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86", "scopes": [], "tokenLifeTime": 3600, "tokenRefreshLimit": 0, "authorizationUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize" ], "accessTokenUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken" ], "redirectUris": [ "https://hostname:18152/portal/rest/v1/oauth/callback" ], "refreshTokenUris": [ "https://hostname:5543/invoke/pub.oauth/refreshAccessToken" ], "type": "OAuth2" }, { "claimsets": [ { "name": "JWT default claims set", "claims": [ { "key": "app_id", "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a" } ] } ], "accesstoken_uris": null, "type": "JWT" } ] }
Update the application in Developer Portal by making a REST call to:
PUT /rest/v1/applications/id?eventId=eventId
Sample request
PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=ebdcef36-1bf6-4998-9556-9fa38b3785b9 { "name": "Petstore App", "credentials": [ { "expiry": null, "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844", "type": "APIKey" }, { "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53", "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86", "scopes": [], "tokenLifeTime": 3600, "tokenRefreshLimit": 0, "authorizationUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize" ], "accessTokenUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken" ], "redirectUris": [ "https://hostname:18152/portal/rest/v1/oauth/callback" ], "refreshTokenUris": [ "https://hostname:5543/invoke/pub.oauth/refreshAccessToken" ], "type": "OAuth2" }, { "claimsets": [ { "name": "JWT default claims set", "claims": [ { "key": "app_id", "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a" } ] } ], "accesstoken_uris": null, "type": "JWT" } ] }
Decrease the scope of an application by making a REST call to the following endpoint:
POST /rest/v1/requests
For example, to remove petstore2 from the previously created application, Petstore App.
POST /rest/v1/requests { "context": { "application": "6179b933-1382-4e1a-becc-239dcfeaaa6d", "apis": [ "842c3e33-5c4b-4abf-b827-1a194affde50" ] }, "type": "APPLICATION_API_DEREGISTRATION_REQUEST" }
Sample webhook payload sent to the third-party gateway
{ "executor": { "id": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4", "email": null, "lastname": "System", "firstname": "Administrator", "name": "administrator" }, "source": { "id": "6179b933-1382-4e1a-becc-239dcfeaaa6d", "externalref": null }, "contextdata": { "api": { "id": "842c3e33-5c4b-4abf-b827-1a194affde50", "externalRef": "24372f80-072e-455f-9235-5c01fbe6f139" } "application_id": "6179b933-1382-4e1a-becc-239dcfeaaa6d" }, "type": "REVOKE_ACCESS_TOKEN", "creationdate": "2022-01-10 15:47:38", "eventid": "8115a10f-451f-4cce-9bb6-7beb1e4722d3", "status": "NEW" }
Update the application in Developer Portal by making a REST call to:
PUT /rest/v1/applications/id?eventId=eventId
Sample request
PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=8115a10f-451f-4cce-9bb6-7beb1e4722d3
Check the status of an application and the list of APIs associated with it by making a REST call to:
GET /rest/v1/applications/id
Sample request
GET /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d { "name": "Petstore App", "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4", "id": "6179b933-1382-4e1a-becc-239dcfeaaa6d", "documentType": "APPLICATION", "providerRef": "7ecefe01-efc7-43e4-9a19-57c3a761e252", "access": { "teams": [], "users": [] }, "apis": [ "842c3e33-5c4b-4abf-b827-1a194affde50", "717eaf03-3c59-448e-8acb-7f3a52667932" ], "credentials": [ { "expiry": null, "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844", "type": "APIKey" }, { "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53", "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86", "scopes": [], "tokenLifeTime": 3600, "tokenRefreshLimit": 0, "authorizationUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize" ], "accessTokenUris": [ "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken" ], "redirectUris": [ "https://hostname:18152/portal/rest/v1/oauth/callback" ], "refreshTokenUris": [ "https://hostname:5543/invoke/pub.oauth/refreshAccessToken" ], "type": "OAuth2" }, { "claimsets": [ { "name": "JWT default claims set", "claims": [ { "key": "app_id", "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a" } ] } ], "accesstoken_uris": null, "type": "JWT" } ], "status": "LIVE", "slots": { "$stage": "X Gateway" }, "deleted": false, "description": "This application is used for building petstore app", "app_type": "API" }
When any application creation, scope increase, or scope decrease transactions fail, you can retry the failed transaction using the following REST calls:
GET /rest/v1/applications/applicationId/requests
This request returns the list of requests made for an application by the current user (signed in user or authorization used in the REST call). You must provide the required application Id.
Sample response
{
"result": [
{
"owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
"id": "0d88fdbf-457b-489f-85bf-fb6678474649",
"modified": "2022-02-10T12:43+0000",
"created": "2022-02-10T12:43+0000",
"documentType": "USER_REQUEST",
"type": "APPLICATION_CREATION_REQUEST",
"status": "DELIVERY_UNSUCCESSFUL",
"application": "8d67856d-476f-492c-a82d-d274501ad08a",
"state": {
"7f8060c1-056e-47d1-8785-83a3eb8f5c88": "DELIVERY_UNSUCCESSFUL"
}
}
],
"count": 1
}
From the list of requests returned in the response, you can view the failed requests and retry them using the below REST call with the request Id and state Id values:
PUT /rest/v1/requests/requestId/retry?state=stateId
Sample response
{
"code": 200,
"message": "User request retried successfully"
}
Publishing API analytics to Developer Portal
The integrated gateways can provide the transactional events of published APIs in Developer Portal to allow users to view the API analytics in Developer Portal.
To publish API analytics in Developer Portal
Make a REST call to the following endpoint:
POST /rest/v1/events/transactions
Sample request
POST /rest/v1/events/transactions { "request": null, "nativeHttpMethod": "get", "apiName": "petstore1", "responseCode": 200, "apiVersion": 1.0, "providerTime": 4711, "apiId": "842c3e33-5c4b-4abf-b827-1a194affde50", "applicationName": "Sample", "applicationIp": "127.0.0.1", "consumerId": "567f89cb-8182-3272-b69e-5d8532eb3ac5", "totalTime": 6264, "operationName": "/pet/findByStatus", "totalSize": 4663, "response": "******Some String response******", "applicationId": "6179b933-1382-4e1a-becc-239dcfeaaa6d", "consumerName": "john.doe@sample.com" }
Next steps:
- You can view the analytics from the Developer Portal dashboard.