Publish APIs

In the first method, the aan administrator or API owner uses the aan to publish the API. Portal-published APIs usually have simple policies that are based on one or more policy templates that the API proxy administrator created.
apip42
HID_PublishAPIs
Two methods for publishing an API on the 
API Portal
 exist. APIs published from the 
API Portal
 are named Portal-published APIs. APIs published from the API proxy are named Gateway-published APIs.
In the first method, the 
API Portal
 administrator or API owner uses the 
API Portal
 to publish the API. Portal-published APIs usually have simple policies that are based on one or more policy templates that the API proxy administrator created.
 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 .
In the second method, the API proxy administrator uses the CA Policy Manager application and API proxy to publish the API. Gateway-published APIs usually have sophisticated policies that the API proxy administrator created. You cannot use the 
API Portal
 to add policy templates to Gateway-published APIs. After the API proxy administrator publishes an API, the 
API Portal
 administrator or API owner enables it on the 
API Portal
 to make it available to developers.
 In a multi-cluster environment (your 
API Portal
 is integrated with multiple API proxies), we recommend using only Portal-published APIs. 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.
In this article:
 
 
Publish APIs with the 
API Portal
 
You can use the API wizard in the 
API Portal
 to publish APIs. 
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
The sample policy templates have the same parameters:
    • Debug mode: When troubleshooting the API, turn on Debug mode to get verbose responses.
    • SLA, Email, and SMTP Server: If the API does not reply within the SLA period, the SMTP server sends an email alert to the email alert address.
    • SSL: To secure API calls between the API proxy and applications, select SSL.
  •  API management policy templates restrict API queries:
    • Rate Limit Policy
      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 Month Policy
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. 
    • Quota By Day Policy
      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. 
 
Example: Restricting API Usage 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. 
 
Example: Changing 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.
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 file, 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 file and you want to expose your Proxy URL to developers, make sure the file contains the Proxy URL information. 
Publish an API
 
To publish an API on the 
API Portal
:
 
  1. Select the 
    Services 
    icon.
  2. Select 
    Publish
    .
    The APIs page appears.
  3. Select 
    Add API
    .
    The API wizard opens.
  4. (Recommended) On the 
    API Definition
     tab, upload a well-crafted WADL .xml or Swagger .json description file for the API. Only Swagger 2.x is supported. Uploading a Swagger or WADL file pre-fills API details so you do not need to enter them manually. 
  5. On the 
    API Details
     tab:
    • Enter an 
      API Name
       and 
      Version
       number.
    • Enter the 
      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. 
    • Select an 
      API EULA
      . Before developers can get an API key for the API, they must agree to your EULA.
    • Set the 
      Visibility
       of the API:
      • Select 
        Public
         if you want to make the API available to all organizations.
      • Select 
        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.
    • (Optional) If you want only one group of developers to use the API, Select an 
      Organization
      . 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.
    • In 
      Public Description
      , include information that developers must use the API, such as its proxy URL and authentication requirements. The description appears in the API Catalog, API Explorer, and Add/Edit Application wizards.
    • If your API uses Custom Fields, complete the following fields:
      • Environment
      • Notes for Consumers
  6. On the 
    Proxy Configuration
     tab:
    • 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.
    • 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.
      • SSL
      • Debug Mode
      • SLA (ms)
  7. Select 
    Create
    .
  8. (Optional) If you attached an API description file to the API, use the API Explorer to test the API. For more information, see Test and Explore APIs.
 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.
Customize Routes for Portal-Published APIs
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.
 
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.
Publish APIs with the API Proxy and Policy Manager
API proxy administrators can use the Policy Manager and API proxy to publish APIs. On the 
API Portal
, the state of new Gateway-published APIs is unpublished. Developers cannot access them until the 
API Portal
 administrator or API owner enables them, which involves assigning the APIs an API EULA.
  • Do not copy and paste Gateway-published APIs (that is, services with the Set as Portal Managed Service Assertion in their policy) in the Policy Manager. The reason is that the original and copy will have the same API ID.
  • To allow the API Explorer to consume APIs that have policies or policy templates containing the Return Template Response to Requestor Assertion, clear the assertion's 
    Send Response Immediately
     checkbox.
  • For hybrid customers, if your on-premise Gateway requires a proxy setting for any outbound traffic or connections, you will need to modify the Routing Assertions in your specific policies or services.
Publish Gateway-Published APIs
 
To publish an API on the API proxy:
 
  1. In the Policy Manager, log in to the API proxy.
  2. Add an API service to the API proxy.*
  3. Open the API service in the Policy editor.
  4. Use the 
    Include Policy Fragment
     assertion to add the 
    Portal Service Preface
     fragment to the beginning of the API service.
  5. Drag the 
    Set as Portal Managed Service
     fragment to the API service below the Portal Service Preface fragment.
  6. Select 
    Save and Activate
    . After the API proxy and 
    API Portal
     synchronize, the API appears in the 
    API Portal
     on the APIs page.
    GWPublishedAPI1.png  
  7. Access the Service Properties for the API service. Select the HTTP/FTP tab and then enable the 
    Options
     HTTP method.
* For details about how to add an API service to the API proxy, see the API Gateway online documentation.
Enable Gateway-Published APIs
 
To enable a new Gateway-published API on the 
API Portal
:
 
  1. Log in to the 
    API Portal
     as an administrator or API owner.
  2. Select the 
    Services 
    icon.
  3. Select 
    Publish
    .
    The APIs page appears.
  4. Select the API from the list.
    The details page for that API appears.
  5. Select 
    Edit
    .
  6. Select 
    API Details
    .
  7. In API Details, select an 
    API EULA
    .
  8. Select 
    Save
    .
Enable Analytics for Gateway-Published APIs
Metrics capturing for Gateway-published APIs requires setting a couple of context variables and installing a set of API Portal Integration Snippet policies on your API service policy.
Perform the following steps to install and integrate the API Portal Integration Snippet policies with your Gateway APIs.
 
To enable analytics for Gateway-published APIs:
 
  1. Install API Portal Integration Snippet policies using the following command:
    curl -k --user '<your_user>:<your_password>' --data @CA_APIM_Portal_policy_snippet_for_gateway_published_api_042018.xml -H "Content-type: application/xml" -X PUT "https://your-tssg:8443/restman/1.0/bundle"
    The following policy fragments and encapsulated assertions are installed:
    • API Portal Integration Fragment - API Key
    • API Portal Integration Fragment - OAuth 2.0
    • API Portal Integration Fragment - Post Route
     The API Portal Integration Snippet policies do not have routes within them. It is assumed that these snippets layer a default protection (API Key or OAuth) and metrics. To capture response status and total routing time, use the Post Route snippet.
    The new snippets appear in 
    Policy Assertions > Internal Assertions 
    palette:
      image2018-3-14 13:18:22.png  
  2. Incorporate the new snippets into your API service:
     Be sure to enable 
    Set as Portal Managed Service
     in your API service. This can be found in 
    Internal Assertions > Set as Portal Managed Service
    .
    1. From the 
      Internal Assertions
       list, add 
      API Portal Integration Fragment - API Key
       or 
      API Portal Integration Fragment - OAuth 2.0 
      snippet to your API service, depending on your method of API protection.
    2. Establish your route and other policy logic for the snippet.
    3. Add 
      API Portal Integration Fragment - Post Route 
      to your API service. To do so, select from the following methods:
      • If your policy has only one route and uses the default response, incorporate the Post Route as an Include Fragment.
        Go to 
        Policy Logic > Include Policy Fragment
        , and select 
        API Portal Integration Fragment - Post Route
        .
        image2018-3-14 13:30:9.png  
      • If you want full control on which response code and routing time to store, add the Post Route internal assertion.
        Go to 
        Internal Assertions
        , add
         
         
        API Portal Integration Fragment - Post Route
        , and specify your desired values.
        image2018-3-14 13:29:37.png
  3. Enable CORS and API Explorer.
    Although the integration snippets have CORS support by default, do the following to enable the API on API Explorer:
    1. Right-click on your API and open 
      Published Service Properties
      .
    2. Under 
      HTTP/FTP > Allowed HTTP Methods
      , enable 
      OPTIONS
      .
    3. Select 
      OK
      .
  4. Test your API and view the Analytics report. You should now be able to view API hits for your Gateway-published API.