Providers

Overview

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?

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

  1. Click the user menu icon from the title bar and click Manage providers.

  2. Click Create provider.

  3. Provide Provider1 in the Name field.

  4. Select the pet_v1 and pet_v2 APIs from the APIs field.

  5. 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.

  6. Click Save.

    The new provider appears in the API providers page.

How do I map an API or a callback URL to a provider?

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

  1. Click the user menu icon from the title bar and click Manage providers.

  2. Click the edit icon next to the provider, provider1.

  3. click Add in the API section.

  4. Select pet_v3 from Add APIs.

  5. 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:

Next steps:

Third-party API Gateway Configuration

You 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

  1. 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:

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:

To create and attach webhooks

  1. 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?

  2. 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:

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

  1. 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.

Next steps:

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:

  1. 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.

  2. 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.

Sample request

PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=8115a10f-451f-4cce-9bb6-7beb1e4722d3

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

  1. 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: