Publisher > New
The Publisher allows you to create REST APIs and manage those APIs. When you create an API, you define the general settings, the backend service, one or more endpoints, and rate-limiting policies for the API.
You must understand REST and know how to create APIs. For more information, see the RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content page.
Secure API Manager stores the APIs on a specific Identity Server cluster. You must select which Identity Server cluster you want to use when you create the APIs. If you have internal and external Identity Server clusters, you can use them to further separate the APIs. Use the following information to help you create an API.
Publisher > New > General
The general settings allow you to give the API a name, and add a description, a version, and tags to help you easily search for the API. You also must define the backend service, define endpoints, and define rate-limiting policies for the API.
To define the general settings for the API:
Ensure that you selected the appropriate Identity Server cluster on the main page of the Publisher before proceeding.
Click General, then define the general settings for the API:
Specify a unique name for the API.
Select the type of API you want to create. With this release, Secure API Manager supports only REST APIs. You cannot change the API type.
Specify the version of the API.
Specify a detailed description of the API so that anyone who uses the API understands what it does. If you clone the API, update the description of the API to describe the differences between the APIs.
Specify the base URL path to the endpoint for the API. You can define this path to be whatever you want.
Select one of the available subscription tiers to control the number of authorizations to the API. Secure API Manager administrators create these Limiting Policies during the configuration of the API Gateway. The Limiting Policies protect the API Gateway from receiving too many requests.
Specify a tag for the API to simplify searching for the API. Secure API Manager includes the specified tags as search parameters for the APIs.
Select whether the API communicates over HTTP or HTTPS.
Click OK to save the API.
or
Click Backend Service to define the backend service that the API uses.
If you click Show JSON, you can view the API in JSON.
Publisher > New > Backend Service
Secure API Manager provides an automatic validation of SSL for the backend service when you include SSL in the API. It validates the SSL connection in two ways:
Validating the backend service server's certificate chain to either a well-known trusted root or a configured trusted root.
Validating that the backend service domain name matches the name in the backend service server's certificate.
By default, Secure API Manager has the backend service SSL certificate validation enabled. You can disable it for testing purposes or in situations where network professionals determine that it is not needed. You can disable the backend service SSL certificate validation process by deselecting Validate SSL Certificate when you edit an API. However, we recommend that you always leave it enabled.
Disabling the backend service SSL certificate validation means that you do not have to have a Trusted Root certificate in the backend service configuration.
Enabling the backend service SSL certificate validation means:
If the backend service server's certificate uses a well-known trusted root certificate, then you do not have to configure a Trusted Root for the Backend Service.
If the backend service server's certificate does not use a well-known Trusted Root certificate, then you must configure a Trusted Root for the backend service. The Trusted Root must follow these guidelines:
Each certificate in the chain:
Must be in PEM format
Must have no duplicate certificates
Must be a well-formed certificate chain
Secure API Manager uses the domain names or IP addresses you added when creating or editing an API under Backend Service > Services as the value to match against the server certificate's subject name. Secure API Manager uses domain names if one exists; otherwise, it uses an IP address. This means that if you use an IP address in the Backend Service > Service definition, the backend service server certificate must include a subject alternate name detailing the IP addresses you added.
To define the backend service:
Ensure that you have defined the general settings before defining the backend service.
Click Backend Service, then define the settings for the backend service of the API:
Specify the name of the backend service.
Select whether the service on the backend service communicates over HTTP or HTTPS.
IMPORTANT:The protocol that you select is the only protocol allowable for any backend service that you add to this API. You cannot specify an HTTP backend service as well as an HTTPS backend service under the same API. Every backend service that you add to this API must be reachable by the protocol you select in this field.
Specify the URL context of the service on the backend service.
Paste the trusted root certificate or the chain of certificates in the .pem format from the backend service. The process of validating the backend service certificates contains multiple ways of providing this information. Ensure that you understand the process of validating the backend service certificates to have this option work.
Click Add Service to define the settings for one or more of the backend services that the API accesses:
Specify the fully qualified DNS name of the backend service.
Specify the port that the backend service uses. By default, HTTP uses 80 and HTTPS uses 443.
Click Advanced to define advanced options for the backend service.
Define and validate the SSL handshake configuration using the following information:
Select whether you want Secure API Manager to validate the SSL chain to the backend service. We recommend that you leave it enabled for security reasons.
Enable Server Name Indication (SNI) and specify a host name if the backend service is a virtual host using TLS and the backend service selects the destination based on SNI.
SNI is an extension to the Transport Layer Security (TLS) computer networking protocol by which a client indicates which host name it is attempting to connect to at the start of the handshaking process. SNI allows services to present multiple certificates on the same IP address and TCP port number, thus allowing multiple secure (HTTPS) websites (or any other service over TLS) to be served by the same IP address without requiring all those sites to use the same certificate.
If you did not specify a domain name, Secure API Manager uses the host name from the backend service definition. Secure API Manager always sends the host header with the upstream domain name in the proxied requests.
Specify the host name to use to validate the SSL certificate and the SNI configuration. If you do not specify a name, Secure API Manager uses the host name of the backend service you specified in Step 3.
Define the API request to the backend service configuration using the following information:
Select this option to pass authorization headers to the backend service through the API calls.
Secure API Manager added the name of the backend service you defined in Step 3. You can add additional headers, edit the headers, and delete the headers. If you edit and change the value of the host header, Secure API Manager updates the value you defined in Step 3 with this new value.
Click OK to save these changes.
Click OK to save the API.
or
Click Endpoints to define the endpoints for the API.
(Optional) click Show JSON to view the API in JSON.
Publisher > New > Endpoints
Secure API Manager allows you to define as many endpoints for an API as you need. It also provides the ability to add parameters to each endpoint. You use the endpoints to help with the communication between client APIs and server APIs. You must know the endpoints for your API to be able to define them. You can add endpoints to an API after you have created the API.
To define endpoints:
Ensure that you have defined the general settings and the backend service for the API before proceeding.
Click Endpoints > Add Endpoint to define the endpoints for the API.
Click General, then define the general settings for the endpoint of the API:
Select the appropriate REST methods for the API. The methods define the action that the API performs. For a definition of each method, see:
Specify the URL path for the API endpoint. The path can be anything that you want. The Publisher displays the path you specify under this field as Access at http(s): so that you can verify that the path is correct.
Specify the base of the URL for the backend service. The Publisher displays the path under this field as Backend Service Endpoint Base URL: so that you can verify that it is correct.
Select how you want to include the backend service URL to the API. You can do nothing, prepend, append, or replace the backend service URL in the API.
Specify the mime type of the API endpoint. For example, application/json or text/html.
Click Parameters, then click Add Parameter to define the parameters for the API:
Specify a name for the parameter.
Select whether the parameter performs queries, contains data, or is a header.
Specify a detailed description of the API parameter so that other people can understand the endpoint parameter.
Select the appropriate data type of the parameter.
Specify the value for the parameter.
Select the type of action the parameter performs.
Select Required if the parameter is required for the API endpoint.
Click OK.
(Optional) To add additional parameters, click Add Parameter, then repeat Step 4 and Step 5 for each additional parameter.
(Optional) To add additional endpoints, click Add Endpoint, then repeat Step 3 through Step 5 for each additional endpoint.
Click OK to save the API.
or
Click Rate Limiting Policies to define rate-limiting policies per subscription and per user.
(Optional) Click Show JSON to view the API in JSON.
Publisher > New > Rate Limiting Policies
Secure API Manager allows you to create rate-limiting policies to protect the throughput to the backend service so that is not overwhelmed. There are three types of rate-limiting policies:
Limiting Policies: These policies are per API and the Secure API Manager administrator is responsible for creating and maintaining the Limiting Policies. These Limiting Policies protect the API Gateway from being overwhelmed with requests.
Subscription Rate Policies: These policies are per subscription, and per API. The API developers are responsible for creating and maintaining the Subscription Rate Policies.
Subscription User Rate Policies: These policies are per user, per subscription, and per API. The API developers are responsible for creating and maintaining the Subscription User Rate Policies.
You select the Limiting Policies in the Subscription Tier when you define the general settings for the API. If you have questions about what the Limiting Policies allow, you can also ask the Secure API Manager administrator for more details.
As the API developer, you can create two additional rate-limiting policy types. Limiting Policies take precedence over Subscription Rate Policies and Subscription User Rate Policies. For example, you create a Subscription Rate Policy that allows 5,000 requests per second. The Limiting Policy allows only 1,000 requests per second. You will see a maximum of 1,000 requests per second. The Limiting Policies take precedence over these other rate-limiting policies to protect the functionality of the API Gateway.
To define the rate-limiting policies:
Ensure that you have defined the general settings, the backend service, and the endpoints for the API before you proceed.
Click Rate Limiting Policies, then define the appropriate rate-limiting policy for your environment.
Secure API Manager applies these policies per subscription to the API.
Secure API Manager applies these policies per user and per subscription to the API.
Click New Policy for the appropriate rate-limiting policies for your environment, then use the following information to create the rate-limiting policy:
Specify the number of requests per the time period, then select the time period you want to use. Read the information about the request count policy to understand how Secure API Manager processes the requests to the APIs.
Specify the maximum number of requests that Secure API Manager allows during a certain period of time.
Specify the amount of time when Secure API Manager limits the requests to the APIs in seconds, minutes, or hours.
If required, define a Burst Rate Limit for the users and subscriptions of this API. to help control the number of requests that happen during the specified time period. The Burst Rate Limit works only if you set the values to be more restrictive than the Quota.
Select this option to be able to define the optimal burst rate limits for the quota. If you do not select this option, you cannot define anything else for this rate-limiting policy.
Specify the maximum number of requests that Secure API Manager allows during a certain period of time. For the Burst Rate Limit to work, this value must be smaller than the value you defined in the Quota.
Specify the amount of time when Secure API Manager limits the requests in seconds, minutes, or hours. This value must be smaller than the value you defined in the Quota.
Click OK to save the API.
(Optional) Click Show JSON to view the API in JSON.