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
To publish an API on the API Portal:
  1. Log into the Portal as an administrator or API owner. 
  2. Select 
    Publish
    . A list of APIs appears.
  3. Click 
    Add API
    to start the publishing workflow. 
    image2019-2-8_16-13-14.png
  4. The
    API Definition
    page opens.
    Do you have a well-crafted WADL, .xml, or Swagger 2.x json definition file for the API?  For more details, see About API Description Files
    If yes, click
    Choose File,
     upload the file, then click
    Next
    Otherwise, click 
    Next
     and provide API details manually.
  5. The
    API Details
    page opens.
    If you uploaded an API definition file, the fields are already filled with values. You are alerted to any mandatory fields that do not have assigned values.  
    Provide values as follows:
    FIeld
    Notes
    API Name
    Maximum name length is 255 characters. Name must be unique.
    Version
    The value for this field can only contain 0-9 and be delimited with . _ and - characters.
    Location of API
    The API proxy routes requests from applications to the location of the API behind the API proxy. Developers do not see this information.  Use a context variable to Route the API to Multiple Data Centers.
    API EULA
    Select an available End User License Agreement (EULA). Before developers can get an API key for the API, they must agree to your EULA.
    Visibility
    One of the following values:
    • Public
      – if you want to make the API available to all organizations.
    • Private
       if you want to make the API available only to the organization selected in the 
      Organization
       field (if any) and to organizations that have the API in their account plan.
    Organization
    Optional. If you select an Organization from the list, only developers associated with this organization can use the API.
    The Organization drop-down list displays 10 results at a time, displaying the next 10 results when you reach the end of the list. It also allows you to enter text so you can do a keyword search.
    Public Description
    Optional. The description appears in the API Catalog, API Explorer, and Add/Edit Application wizards.  Use this field to provide developers with API information such as its proxy URL and authentication requirements. Maximum description length is 255 characters.
    Private Description
    Maximum description length is 255 characters.
    Custom Fields
    If your API uses custom fields, provide information here.
    Click
    Next
    .
  6. The 
    Proxy Details
    page
    opens.
     
    Complete the 
    Proxy URL
    , which is the public URL of the API on the API proxy. Developers use this URL in their applications to send requests to the API.
    For 
    Policy Templates
    , select a policy template, select 
    Add
    , and set its parameters. 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. See Policy Templates.
    Click
    Next
    .
  7. The
    API Explorer
    page opens.
    Configuration here is optional and only available if you have used an API Definition file.
    To use the API Explorer to test your API, select and configure an Authentication type.  For more information, see Test and Explore APIs.
  8. Click
    Create
    .
    Your API is published. A page shows you an Overview of your enabled API. 
How to 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
We recommend that you upload a well-crafted WADL .xml or Swagger 2.x .json file for each Portal-published API. Without a WADL or Swagger, you cannot use the API Explorer to test the API and developers cannot use the API Explorer to try the API. For more information, see the WADL and Swagger specifications.
The API Explorer consumes only APIs that have secure (HTTPS) endpoints. If an API has a secure and unsecure endpoint, ensure that the API WADL or Swagger file points to the secure endpoint.
If you are uploading a WADL or Swagger 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.