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:

API partner isolation

API partners can be organizations or users who expose their APIs through Developer Portal. As a Developer Portal administrator, you can enable partners to isolate their APIs so that the partners can determine the users or user groups that can access their APIs. Isolation of assets will also restrict the APIs that the providers have access to.

To use this feature, users must register to Developer Portal as API partners.

API Partner Capabilities

API partners can

Manage APIs

Partner users can publish APIs from API Gateway or create APIs in Developer Portal, enrich them, and assign the APIs to the required private communities. To allow consumer users to view APIs, API partners can include them in the corresponding private communities. They can also unpublish or delete the required APIs.

Partners can publish their assets to:

  • Private communities. Consumers, who are part of the community can view and request applications to try those APIs. Other consumers cannot view those assets.
  • Public community. This does not support assets isolation based on partners.

    • API partners can also create their own communities. They cannot edit other communities.

    Manage packages

    Similar to APIs, partner users can publish packages from API Gateway to the required private communities. Consumers, who are a part of the published communities can view the packages and subscribe to them.

    View Dashboard

    API partners can view the analytics of APIs and applications usage from their Dashboard section. This section includes only the analytics of assets that the partners have published or have been assigned as owners.

    Manage Communities

    Once an API partner registers with Developer Portal, administrators can associate them with private communities as administrators. As community administrators, partners can manage their communities, assets associated with their communities, and the community members.

    Partners can also create their own communities and manage them.

    API gallery

    API partners can view:

  • APIs published to the private communities that they are members of.
  • APIs that they published (regardless of their communities).
  • APIs that are assigned to them by other partners.

    • Change asset ownership

    API partners can assign their assets to other partners; and the partners can manage the assigned to them by other partners. For more information, see Assigning Asset Ownership.

    Onboarding an API partner

    As an administrator, you must register users with Partner privilege, and add them as administrators of the required communities. As stated earlier, partners can manage their assigned communities, assets associated with their communities, and the community members.

    To onboard an API partner

    1. Create a user with the Partner privilege. For information on adding users, see How do I add a user?.

    2. Provide the user credentials to the required users.

    Next steps:

    Assigning Asset Ownership

    As an API partner, you can assign APIs to other partners; and they can make these assets available to their community members. You can assign an API to the required users or teams. The owners thus assigned to an API can manage the API.

    To assign asset ownership

    1. Click the menu options icon from the title bar and click Manage assets.

    2. Click APIs or Packages depending on the asset you want to assign.

    3. Click next to the required asset.

    4. In the Assign owners, select the required partner from the Users tab. This field displays only the users who have the Partner role assigned to them. Users who have the API Provider or Administrator role can view all APIs. Hence, only the users with the Partner role are displayed.

    5. Click Assign. The selected partners become owners of the asset.

    Next steps:

  • Partners can manage the assets assigned to them by other partners.