Publish APIs with the API Portal

This page describes how to create Portal-published APIs.
This page describes how to create 
Portal-published
 APIs.
For Gateway-published APIs, see Publish APIs with the API Proxy and Policy Manager.
In this article:
About Portal-published APIs
Portal-published APIs usually have simple policies that are based on one or more policy templates. 
The API Portal administrator or API owner uses the API Portal to publish the API. API Portal administrators can use the Authorization API to let users with the organization administrator or developer role manage APIs in their organization. For more information, see Authorization API .
We recommend using only Portal-published APIs in a multi-cluster environment where your API Portal is integrated with multiple API proxies.
If you fail to migrate a Gateway-published API in a multi-cluster environment, the API might appear and then disappear from the APIs section on the Portal. To resolve this issue, use the Gateway Migration Utility (GMU) to migrate all Gateway-published APIs to all clusters. To learn more about the GMU, see "Gateway Migration" in the API Gateway online documentation.
Create a Portal-Published API
For more information, see Create and Set Permissions for APIs
Route the API to Multiple Data Centers
To route the API to multiple data centers, use context variables in the API location. For example, enter the API location:
 
http://localhost:8080/echo?name=${gateway.cluster.hostname
}
The value in the context variable 
${gateway.cluster.hostname}
 is used for routing in policy for the API.
 For more information about context variables, see "Context Variables" in the API Gateway online documentation.
About API Description Files
It is recommended that you upload a well-crafted definition file for each Portal-published API. This can be a WADL .xml or Swagger .json for REST APIs. For SOAP APIs, the attached WSDLs and XSDs can be downloaded for use in any external SOAP client like SOAP UI.
Without a definition file, you cannot use the API Explorer or Swagger UI to test the API and developers cannot use the API Explorer or Swagger UI to try the API. For more information, see the following specifications:
API Explorer is only accessible through the API Portal/Ingress tenant. If you are using an external tenant, test and explore APIs using the Swagger UI instead. For more information about testing with Swagger UI, see Test and Explore APIs.
The API Explorer consumes only APIs that have secure (HTTPS) endpoints. If an API has a secure and unsecure endpoint, ensure that your definition files point to the secure endpoint.
If you are uploading a definition file and you want to expose your Proxy URL to developers, make sure the file contains the Proxy URL information. 
Control API Access with Policy Templates
You can use policy templates to customize how a policy on the API proxy processes calls to an API using the API wizard. API publishers commonly use authentication and quota policies to control API access. The API proxy administrator creates the policy templates.
 When you publish an API, you can combine multiple policy templates. If you select multiple policy templates, ensure that you select them in the order that you want the API Proxy to apply them. Also note that some templates might be incompatible with other templates. Conversely, some templates might need to be combined with another template. For more information about your policy templates, contact your API proxy administrator.
Out-of-the-box, the API wizard also provides sample policy templates, which API proxy administrators can revise. The default policy templates provide samples for authenticating calls to APIs, and for managing API usage.
Authentication policy templates provide different options for authenticating calls to APIs:
  • No authentication
  • API Key authentication
  • OAuth 2.0
Available policy templates are as follows:
Policy Template
Template Type
Recommended Environment
Notes
API Key
Standard
Testing only
Applies an API Key check to all API access calls.
No Auth
Standard
Testing only
Applies no authentication check. Useful for proxying third-party APIs (such as Twitter) that have their own authentication requirements.
OAuth 2.0
Standard
Production
Applies an OAuth 2.0 check to all API access calls. Appropriate for both two and three-legged OAuth implementations.
Supports the following grant types:
  • Implicit
  • Client credentials
  • Resource owner password credentials
  • Authorization code
Rate Limit Policy
API management
Restricts the number of times that an API can be queried in a second. For example, a rate limit of 1 prevents all the applications that use that API from accessing it more than once per second. 
Quota By Day Policy
API management
Restricts the number of times that an API can be queried in a day. For example, a quota limit of 1 ensures that all the applications that use that API can only access it once per day. 
Quota By Month Policy
API management
Restricts the number of times that an API can be queried in a month. For example, a quota limit of 1 ensures all the applications that use that API can only access it once per month. 
The standard policy templates have the same parameters:
  • Debug mode –  When troubleshooting the API, turn on Debug mode to get verbose responses.
  • Email – The address used by the SMTP server to send an email alert. 
  • SLA –  The Service Level Agreement (SLA) period expressed in milliseconds. If the API does not reply within the SLA period, the SMTP server sends an email alert to the email alert address.
  • SMTP Server – Your email gateway
  • SSL – To secure API calls between the API proxy and applications, select SSL.
How to Restrict API Use by Application
 
You can use the Rate Limit, Quota by Month, and Quota by Day policies with account plan policies to restrict API usage for a specific application. For example, you can set the API Rate Limit to 10 per second, and the Account Plan Rate Limit to 1 per second. The application using the API 
and
 the account plan can only access the API once per second. 
How to Use Quota and Rate Limits
 
The following example shows the impact of changing a quota or rate limit, based on the day of the change.
A customer sets the Quota by Day to 100 for an API. When that API is consumed 100 times, the API is no longer accessible. The customer then requests that the quota is increased to 200 on the
 same day
. The API can be consumed an extra 100 times on the current day because the new daily limit has not been reached yet.
If the customer requests the quota to be changed to 200 on the 
next day
, the API can be consumed 200 times the next day.
The scenario applies for Quota by Day and Quota by Month.
Sample policy templates exist on every cluster that is enrolled with the Portal. However, revised sample policy templates and new policy templates exist only on the API proxy on which they are revised or created. In a multi-cluster environment, use the Gateway Migration Utility (GMU) to migrate these templates to all the enrolled API proxies. To learn more about the GMU, see "Gateway Migration" in the API Gateway online documentation.
Known Issue:
 Unexpected behavior will occur if you fail to migrate a custom policy template to all the API proxies in a multi-cluster environment. The custom policy template might appear and then disappear from the policy template section on the Proxy Configuration tab of the API wizard.
Customize Routes
When API owners add a Portal-published API, they specify the location of the API. API proxy administrators can use the Policy Manager to customize how the API proxy routes calls to the API.
To enable route customization for a Portal-published API:
  1. Use the Policy Manager to log in to the
     
    API proxy as an administrator.
  2. Open the API policy in the Policy Development window.
  3. Locate and double-click this line in the policy:
    Set Context Variable override_template_routing as String to: false
     
  4. In the Context Variable Properties, change 
    false
     to 
    true
    .
  5. Select 
    OK
    . Then save and activate the policy.
  james lamothe  
If route customization is enabled on an API, when someone uses the API Explorer to send a request to the API, the response contains an erroneous Access-Control-Allow-Origin header value that the API Explorer cannot process. To prevent this problem, the API proxy administrator must remove the Access-Control-Allow-Origin CORS header from the custom routing section of the API policy. One way to remove that header is to configure the HTTP routing properties to pass only certain response headers.
Filter Response Headers
To filter a Portal-published API's response headers:
  1. In the Policy Manager, open the API Route using HTTP(S) assertion. The HTTP(S) Routing Properties dialog opens.
  2. On the 
    Headers
     tab, select the checkboxes 
    Pass through only certain request headers
     and 
    Pass through only certain response headers
    . Do not change the headers.
  3. Select 
    OK
    . Then save and activate the policy
  http_routing_properties.png  
For more information about routing, see "Route via HTTP(S) Assertion" in the API Gateway online documentation.