Managing API Implementations

Add or modify one or more implementations for your API. Manage deployment zones, policies, and security for each implementation.

API Platform Version: 8.1 and later

Table of Contents

Implementations:
  1. What is an API implementation?
  2. How do I add an API implementation?
  3. How do I add a Sandbox implementation?
  4. What is an implementation pattern and which one should I choose?
  5. How many API implementations can I have?
  6. How do I edit an API implementation?
  7. How do I delete an API implementation?
  8. How do I add or modify a target endpoint for an implementation?
  9. How do I delete a target endpoint for an implementation?
  10. How do I manage orchestration for my implementation?
  11. How do I use the Process Editor?
  12. What is debug mode?
  13. How do I turn on debug mode for my implementation?
  14. How do I specify a listener when adding/editing an implementation endpoint?
Managing Deployment Zones for an API:
  1. What is a deployment zone?
  2. How do I see which deployment zones my API is deployed to?
  3. What does the color coding on deployment zones mean?
  4. How do I add an API deployment zone?
  5. How many API deployment zones can I have?
  6. How do I edit an API deployment zone?
  7. How do I add a new protocol for an API deployment zone?
  8. How do I delete an API deployment zone?
Managing Policies for an API:
  1. What types of policies are available for my API?
  2. What security and monitoring policies are available for my API?
  3. Which policies should I choose?
  4. How can I see details about a policy?
  5. What is the minimum policy requirement for my API?
  6. How do I assign policies to my API implementation?
  7. How do I see which policies are assigned to my API implementation?
  8. How do I set up my API to support CORS?
Managing Keys and Certificates for an API:
  1. How do I manage keys and certificates for my API?
  2. How does the platform support SNI?
  3. How do I set up my API to support SNI?
  4. Related Topics

Implementations:

What is an API implementation?

Different implementations of an API represent the different endpoints of the API in the same lifecycle stage. For example, it is common for an API to have Sandbox and Live implementations.

When you create your initial API definition, the API platform creates the Live implementation automatically. You can create a second implementation for Sandbox, if needed.

If an existing implementation is deleted, you can create another; however, you cannot have more than two implementations of an API at the same lifecycle stage.

Implementation Summary

The Implementations page for your API (API Details > Implementations) will look something like the below:

API Implementations page

In this example, there are three deployment zones available and active for each implementation; therefore, each implementation has three endpoints, one for each deployment zone. You can modify as needed. For more information, see Managing Deployment Zones for an API.

Implementation Details

When you click through on a specific implementation, you'll see the implementation details, something like the below:

API Implementations page

Here, you can manage all aspects of the implementation:

  • Top section: modify metadata about the implementation such as description and proxy URL.
  • Deployments section: modify the technical details about the implementation such as deployment zones and vanity hostname.
  • Policies section: specify policies to be applied to API traffic for this implementation.
  • Certificates section: manage certificates for the implementation.
  • Resources section: view a list of resources for the implementation, and manage processes for individual resources.

Back to top

How do I add an API implementation?

If you create your API by importing an API description document, the platform creates the Live implementation as part of creating the API. In this scenario, it's best to review the API implementation definition, and modify if needed. See How do I edit an API Implementation? below.

If you created your API from scratch, or you want a second implementation for an existing API, you'll need to add a new implementation. Follow the steps below.

To add an API implementation
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click Add.
  4. At the Add Implementation page, provide the following:
    • Implementation Name: choose from the drop-down list available. You can have one implementation for each option available on the list.
    • Description: a short description of the implementation. This field supports Markdown, so you can add formatting. Click the ? sign for help with Markdown, if needed.
    • Pattern: Choose Proxy for a simple scenario where the API implementation has a 1:1 relationship with a back-end physical service/API; then provide the API endpoint that you want to set up a proxy for. Choose Orchestration for a more complex API implementation that might include one or more services, processes, or additional steps.
  5. Click Save.
  6. At the Implementations page, click the link for the new implementation to add additional values. See To edit an API implementation below.

Back to top

How do I add a Sandbox implementation?

If you're designing your API from scratch, there are no implementations until you create them. In this scenario, to add a Sandbox implementation, follow the instructions in To add a new API implementation above.

If you create the API from an API description document, the first implementation is automatically created as a Live implementation.

If you want to add an additional implementation for Sandbox, follow the instructions in To add a new API implementation above.

If you want only a Sandbox implementation, first add the new Sandbox implementation, and then delete the Live implementation following the instructions in How do I delete an API implementation? below.

Back to top

What is an implementation pattern and which one should I choose?

When you're setting up an implementation, you'll need to specify the implementation pattern and then provide additional details.

The implementation pattern determines how you want to go about creating the implementation and/or what existing service you want to use or to base the new service on.

Generally, Proxy is the default. It is appropriate for a simple scenario where the API implementation has a 1:1 relationship with a back-end physical service/API.

For a more complex API implementation, that might include one or more services, processes, or additional steps, choose Orchestration. Later, you can use the built-in Process Editor to fine-tune the process.

Back to top

How many API implementations can I have?

You can have two API implementations for each lifecycle stage. Each implementation represents a different endpoint; generally, Live and Sandbox.

When you create your initial API definition, by default the Live implementation is created. You can create a second implementation for Sandbox, if needed.

If an existing implementation is deleted, you can create another; however, you cannot have more than two implementations of an API at the same lifecycle stage.

Back to top

How do I edit an API implementation?

To edit an API implementation
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to edit. The summary page for the implementation is displayed. There are several sections to the page:
    • General information about the implementation
    • Deployment zone data
    • Policies
    • Certificate
    • Resources
  4. Optional: edit implementation summary values:
    • In the top section, click Edit.
    • Add or modify the description. You can use Markdown if needed.
    • Check or clear the Allow Anonymous Access check box.
    • Check or clear the Approval Required check box (applicable only if anonymous access is not allowed).
    • In the Pattern field, change the implementation pattern if needed. Choose Proxy for a simple scenario where the API implementation has a 1:1 relationship with a back-end physical service/API. Choose Orchestration for a more complex API implementation that might include one or more services, processes, or additional steps.
    • When done, click Save.
  5. Optional: edit deployment zone details:
    • In the middle section, click Edit.
    • Zone: choose a different deployment zone out of the valid values available.
    • Enable Zone: To add or remove deployment zones for the implementation, click the zone on the left and then check or clear the Enable Zone box on the right.
    • Add protocol: click the + tab. At the Add Endpoints overlay, choose the protocol and click Add.

      Note: If you want to use SNI to serve up the implementation's key/certificate, in the HTTPS tab, check the Use Implementation's Key/Certificate for SSL box (requires that API Clients are SNI-compliant).

    • Context Path: defaults to a single forward slash (/) but you can change it.
  6. Optional: edit certificate information for the implementation:
    • In the Certificate section, click Edit.
    • On the Keys and Certificates page, manage keys and certificates. You can upload, download, or delete. When you're done, click Save. For more information, see How do I manage keys and certificates for my API?
  7. Optional: edit policies:
    • In the Policies section, click Edit.
    • Choose to attach or remove policies, and then click Save.
  8. Optional: edit resources:
    • Choose the resource you want to edit. In the Actions column, click the arrow. The Process Editor opens.
    • Edit the process for the resource, and then click Save. For more information, see How do I use the Process Editor? below.

The changes are effective immediately.

Back to top

How do I delete an API implementation?

You can delete one or more implementations for an API.

Note: When you delete an implementation, all apps are disconnected from the implementation, and all process configuration, policies, and endpoints are deleted. This action is not reversible. To set up the implementation again you'd need to recreate from scratch, including policies, process configuration, and endpoints, and apps would need to connect to the new implementation.

To delete an API implementation:
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to delete. The summary page for the implementation is displayed.
  4. At the top right, click Delete.
  5. At the confirmation prompt, click OK. The implementation is deleted.

The changes are effective immediately.

Back to top

How do I add or modify a target endpoint for an implementation?

After your API is set up, you might need to change the target endpoint for a specific implementation, or add a new target endpoint. You can add or change a target endpoint at any time.

To add or modify a target endpoint for an API implementation:
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to modify. The summary page for the implementation is displayed.
  4. In the top section, under Pattern, click the Modify target endpoints link.
  5. On the Endpoints page, you have two options:
    • Edit an existing endpoint: click the Expand icon (...) to expand, and then click the Edit icon (pencil).
    • Add an endpoint: click Add.
  6. Set values for the following fields:
    • Location: enter the full URL for the target endpoint (the actual endpoint for your API; the proxy endpoint relays traffic to the target endpoint).
    • Protocol version: Leave as Unspecified, the default, or specify HTTP 1.0 or HTTP 1.1.

      Note: When Unspecified is selected, the API Gateway takes the HTTP version in the request message and uses it in the downstream request message to the target endpoint. If another version is specified, the API Gateway always uses the specified version for downstream requests.

    • Require Content-Length Header: Check this box if the proxy endpoint should send a Content-Length header to the target endpoint, to indicate the message length.

      Note: If the protocol version is HTTP 1.0, the Requires Content-Length Header field is checked by default and cannot be changed; it is required.

  7. Click Finish to save the endpoint.
  8. Click Finish to exit from the Endpoints page.

Back to top

How do I delete a target endpoint for an implementation?

You can delete a target endpoint. In case the endpoint is in use, make sure users are notified before deleting the endpoint.

To delete a target endpoint for an API implementation:
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to delete. The summary page for the implementation is displayed.
  4. In the top section, under Pattern, click the Modify target endpoints link.
  5. On the Endpoints page, find the endpoint you want to delete. Click the Expand icon (...) to expand, and then click the Delete icon (X).
  6. At the confirmation message, click OK.
  7. On the Endpoints page, click Finish (if you don't confirm on this page, the endpoint is not deleted).

Back to top

How do I manage orchestration for my implementation?

If your API implementation is more complex, and might include one or more services, processes, or additional steps, choose an implementation pattern of Orchestration. Then, you'll be able to use all the features of the built-in Process Editor to fine-tune the orchestration of your API.

To access and use the Process Editor, follow the procedure below. If you need more details about the specific activities available and how you can configure them, refer to the full standalone Process Editor documentation (links below).

For a tutorial video showing an example of using the Process Editor, see Add an API using orchestration (external link).

To access the Process Editor to manage orchestration for your implementation
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to edit. The summary page for the implementation is displayed. There are several sections to the page:
    • General information about the implementation
    • Deployment zone data
    • Policies
    • Certificate
    • Resources
  4. In the bottom section, find the resource that you want to manage the process for.
  5. In the right column, Actions, click and choose Edit Process. The Process Editor opens.
  6. Edit the process for the resource, and then click Save. For more information, see How do I use the Process Editor? below.

Back to top

How do I use the Process Editor?

You can access the Process Editor, used to manage orchestration at the implementation level or for a specific resource (operation), in the developer portal. Depending on your role, you can:

For information about how to use the Process Editor once you're there, use the summary and links below.

Process Editor: summary
  • The Activity Palette on the left includes a selection of tools that you can use to manage orchestration.
  • Drag and drop activities onto the grid as needed.
  • Double-click any activity to open up the Activity Edit page, which offers additional settings and values to customize the behavior of the activity.
  • Be sure to save any work you do in the Process Editor by clicking the disk icon on the left. Before exiting the Process Editor, save changes and make sure you see the confirmation message.
  • To close the Process Editor and return to the Implementation page, click Finish.
Process Editor: additional resources

Use the resources below to become more familiar with the features of the Process Editor:

Back to top

What is debug mode?

API Platform Version: 8.4 and later

Debug mode is a setting that controls the level of logging of API traffic. Debug mode, the second-highest level of logging, records additional information to the API's logs, above and beyond the normal settings.

You can turn on debug mode if there's an issue with the API, in a specific implementation, and you need more information to determine what the problem is. Debug mode requires that there is at least one auditing policy, of any type, attached to the API.

As long as there is an auditing policy attached to the API, when debug mode is turned on the platform adds log entries for each of the steps performed by the underlying infrastructure, for every transaction. The steps recorded in debug mode are:

  • Policy enforcement/implementation
  • Orchestration activity execution

If you turn on debug mode, remember to turn it off when your debug activities are complete. Because it records additional information, which is then also stored, there is a small performance impact as well as a storage impact.

For information about turning on debug mode, see How do I turn on debug mode for my implementation? below.

Back to top

How do I turn on debug mode for my implementation?

You can turn on debug mode in two places:

  • In the Implementation Details page
  • In the Logs page for the API
To turn on debug mode in the Implementation Details page

First, make sure there is at least one auditing policy attached to the API; either Basic Auditing or Detailed Auditing. If there is no auditing policy, transactions are not logged at all.

  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation. The summary page for the implementation is displayed.
  4. In the top section, click the Debug Mode swipe button, as shown below. Debug mode is turned on immediately.

    Turning on debug mode

  5. If needed, use the Go to Transaction Logs link. This is a shortcut to the API > Analytics > Logs page. For more information on the transaction logs, see How do I monitor API usage logs?

Remember to turn off debug mode when you are done.

Back to top

How do I specify a listener when adding/editing an implementation endpoint?

When adding or editing an endpoint for an implementation in the developer portal, the API Admin can specify the listener, choosing from a list of valid listeners available, on the Protocol tabs for the implementation.

The first listener is generated automatically as part of the API creation process. You can specify a listener as part of adding a subsequent implementation, or as part of editing any implementation.

If only one listener for a specific protocol is available for the deployment zone, the listener pull-down does not appear.

To specify a listener
  1. Log in to the Akana API Platform.
  2. Choose the API.
  3. On the left menu, click Implementations to access the Details page for the implementation.
  4. In the Deployments section, click Edit.

    Note: If there are no deployment zones listed in the Zone drop-down list, the Business Admin hasn't added any. The Business Admin sets up deployment zones as part of business organization configuration. See How do I add a deployment zone? (Business Admin help).

  5. If it's not yet checked, check the Enable Zone box. Additional fields are displayed so you can choose from available protocols and settings.
  6. Optional: to delete one or more existing listeners, click the X next to it, as shown below. At the confirmation prompt, click OK to delete the listener.

    Deleting an existing listener

  7. To add a listener, click the + icon, and then choose one or more available listeners, as shown below.

    Adding a listener to an implementation

    Note: this overlay shows all available listeners, even if they are already selected. When you're modifying listeners, it's a good idea to delete existing listeners first, as explained in Step 6 above.

  8. Click Add.
  9. Click Save to save changes and return to the Details page for the implementation.

Back to top

Managing Deployment Zones for an API:

What is a deployment zone?

A deployment zone is a physical location, such as a geographical area or a specific data center, that the API endpoint uses to proxy the API, if the API is hosted on the platform and is using the proxy capability.

One or more deployment zones are configured as part of the platform setup. When the API Admin creates the API, either from scratch or by uploading an API description document, the platform matches the API against the deployment zones that are defined. The API is deployed to all matching deployment zones.

For example, a deployment zone might be defined as being for live implementations only. An API sandbox implementation would not be deployed to this deployment zone.

Back to top

How do I see which deployment zones my API is deployed to?

Once you've added your API, it is automatically deployed to any of the API Platform deployment zones with criteria that match your API definition.

The deployment zones for your API are displayed in a map-like chart, as shown below:

Deployment zones

Deployment zones are assigned to each API implementation when the implementation is created. You can then fine-tune as needed.

Note: If a physical location hasn't been specified for the deployment zone, it shows on the map as Unknown, and the dot appears on the top left of the map.

To view the deployment zones for a specific implementation
  1. Log in to the Akana API Platform.
  2. Choose the API.
  3. On the left menu, click Implementations.
  4. Click the link for the implementation you want to view.

Note: If your API implementation meets the criteria for multiple deployment zones, it has a unique endpoint for each deployment zone.

Back to top

What does the color coding on deployment zones mean?

When you view the deployment zone map for an API implementation, you might see one or more deployment zones.

The platform uses color coding to convey information about deployment zones, as follows:

  • Pale blue—Disabled and not selected
  • Pale green—Enabled and not selected
  • Dark blue—Disabled and selected
  • Dark green—Enabled and selected

Back to top

How do I add an API deployment zone?

You cannot specifically add a deployment zone to an API. Deployment zones are set up by the Administrator; when you add an implementation, deployment zones are assigned automatically based on the criteria for the API and the deployment zones.

However, there are a couple of scenarios that allow you to make an additional deployment zone available to your API:

  • if you disable a deployment zone from your API implementation, you can re-enable it.
  • If a new deployment zone becomes available on the platform, and it matches the criteria for your API, you can then add it to your API.

When you create your API from an API description document, the platform automatically matches up your API definition against the existing deployment zones, and deploys the API to all deployment zones for which it matches the criteria.

Note that Live and Sandbox implementations are likely to be deployed to different deployment zones.

Back to top

How many API deployment zones can I have?

An API can have many deployment zones.

The number of deployment zones for an API is determined by these factors:

  • The number of deployment zones defined on the platform.
  • The eligibility requirements for each deployment zone; for example, a specific deployment zone might be limited to Live implementations, so an API's Sandbox implementation would not have access to it.
  • The API definition.

Back to top

How do I edit an API deployment zone?

When you're adding a new implementation, or editing an implementation that was manually added or automatically generated for your API, you can fine-tune the deployment zone assignments by modifying the settings. You can:

  • Disable/enable one or more deployment zones from the API's implementation.
  • Add a protocol for an existing deployment zone, if additional protocols are available for the specific deployment zone.
  • Add a vanity hostname.
  • Add a context path.
  • Set up a new protocol for the deployment zone, or modify an existing one (from available protocols)
  • Specify whether the deployment zone is included in automatically-generated API documentation.

Note: By default, when the implementation is added for a specific deployment zone, a unique hostname is created; for example, api11192live.developer.acmepaymentscorp.com. Each API has a unique hostname for each valid zone it's deployed in. Your API users can use either the unique hostname generated by the platform or the vanity hostname you provide yourself.

Editing deployment zones for an API

To edit an API's deployment zone assignment for a specific implementation
  1. Follow the steps in To view the deployment zones for a specific implementation to get to the Deployment Zones page.
  2. In the Deployments section (second section of the page), on the right, click Edit.
  3. Choose the deployment zone to edit by clicking in the map view or choosing from the drop-down list.
  4. Choose the protocol to edit by clicking the applicable tab on the right. To add an available protocol, click + and then, in the Add Endpoint dialog, choose the protocol. Available protocols are determined by how the deployment zone is defined; if you don't have the protocol you need, ask a Site Admin or Business Admin.

    Note: If you want your API to support SNI, choose HTTPS and click the Use Implementation's Key/Certificate for SSL checkbox, as shown below. (For more information on implementing SNI, see How do I set up my API to support SNI?)

    Using HTTPS

  5. Change values as needed. For help with the field definitions, see Add Deployment Zone / Edit Deployment Zone Dialog: Field Values below.
  6. Click Save.

Note: If you are not using a vanity hostname, you don't need to provide a context path; the path is already unique to the API implementation.

Add Deployment Zone / Edit Deployment Zone Dialog: Field Values

The Add Deployment Zone / Edit Deployment Zone dialog provides the following:

Map view
To view information about a deployment zone, click the zone on the map.
Zone
Choose from the drop-down list. The list shows all deployment zones that are valid for the specific API implementation.
Enable Zone
Check or clear the box to enable or disable the deployment zone.
Protocol tabs
To add a protocol, click the + sign and choose from additional protocols available (if any; determined by the deployment zone definition as set up by the Site Admin or Business Admin).
Hostname
The generated, unique hostname for the API implementation is displayed.
Use Implementation's Key/Certificate for SSL (HTTPS only)
Check the box if you want to use SNI to serve up the implementation's key/certificate. Requires that API Clients are SNI-compliant.
To support SNI, you must also upload a certificate for the implementation (see How do I manage keys and certificates for my API?).
Provide Vanity Hostname
When an API implementation is automatically created with one or more valid deployment zones, a random prefix is added to the hostname. Check the box if you want to give the implementation a vanity hostname that's easy to remember and in a different domain (for example, api.acmepaymentscorp.com) rather than the unique hostname assigned by the platform.
Note: Whether you use the assigned hostname with the random prefix or a vanity hostname, make sure your hostname is configured in the DNS server as a CNAME to the unique hostname assigned by the platform.
Vanity Hostname (CNAME)
Provide the vanity hostname; for example, acmepaymentscorp.com. Make sure it is mapped to a valid CNAME in the DNS server of the domain for the vanity host.
Context Path
To make the URL unique, use the context path if necessary. The generated hostname is unique to each API implementation, so if you're using the unique hostname you don't need a context path. If you're using a vanity hostname, use the path to make the URL for each API unique.
Calculated Endpoint
The full endpoint for the API implementation is generated based on the settings provided, and is displayed. It is a composite of values: protocol, generated URL or vanity URL, and context path. If the implementation doesn't use a vanity hostname, the calculated endpoint is composed of protocol, assigned URL, and context path if specified.
Publish in API Documentation
You might want to restrict use of a specific endpoint with a generated hostname, for private or internal use. To do this, clear the check box. Only URLs that have this box checked (the default) are included in the API documentation and displayed to users who are not API Admins.

Back to top

How do I add a new protocol for an API deployment zone?

You can add an additional protocol supported by the deployment zone your API implementation is using.

To add a new protocol to an existing deployment zone
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to edit.
  4. In the middle section, click Edit to edit the deployment zone details.
  5. In the protocol section on the right, click the + tab.
  6. At the Add Endpoints overlay, choose the protocol and click Add.

    Note: the list of protocols available is determined by the properties of the deployment zone that the implementation is using. Deployment zones are defined by the Site Admin or Business Admin.

  7. Click Save.

Back to top

How do I delete an API deployment zone?

Deployment zones are set up by the Site Admin and are assigned to your API automatically based on the deployment zone criteria and the API definition. You cannot delete a deployment zone; however, you can disable a specific deployment zone for your API, which achieves the same result.

Any customization of settings is lost when you disable a deployment zone.

To disable a deployment zone for an API
  1. Follow the steps in To view the deployment zones for a specific implementation to get to the Deployment Zones page.
  2. In the Deployments section, on the right, click Edit.
  3. Choose the deployment zone you want to disable, either by clicking in the map view or choosing from the drop-down list.
  4. Clear the Enable Zone check box.
  5. Click Save.

Note: If you previously disabled a deployment zone, you can re-enable it by going back in and checking the box, then editing the settings as needed.

Back to top

Managing Policies for an API:

What types of policies are available for my API?

The platform allows you to secure and monitor your APIs with policies. A selection of policies is available to apply different rules to your API.

There are three main policy categories:

  • Simple Header Security—Used to identify (authenticate) the application that is attempting to consume an API to determine if it is authorized or not. This policy type supports multiple mechanisms for the App to present its identity, including plain text App Id, signed header with X.509 or a shared secret, or OAuth (1.0a or 2.0).
  • Analytics—Collects transaction details including recorded messages for every transaction.
  • OAuth—Provides support for applications performing authentication and authorization using OAuth.

For details, see below.

Back to top

What security and monitoring policies are supported?

The platform offers the preconfigured policies listed below.

AtmosphereApplicationSecurityPolicy
This is a default security policy for Enterprise API Platform applications. It provides support for SHA1 (Shared Secret), allowing the API to authenticate the app.
For full documentation about this type of policy, refer to: Using the API Consumer Application Security Policy (Akana docs site).
Policy Category: Simple Header Security
BasicAuditing
Provides basic auditing of messages. Message metrics are recorded in the Usage Logs Analytics tab. The messages themselves are not audited. For message auditing, use the DetailedAuditing policy.
For full documentation about this type of policy, refer to: Using the Basic Auditing Policy (Akana docs site).
Policy Category: Monitoring
CORSAllowAll
CORS (cross-origin resource sharing) enables users to access resources from within the browser serving a web page, and defines a way in which the browser and the server can interact to determine whether or not to allow the cross-origin request.
The CORSAllowAll policy allows all cross-origin requests.
If you are using the platform as a proxy, you can add the CORSAllowAll policy to allow cross-origin requests to the proxy service.
For full documentation about this type of policy, refer to: Using the CORS policy (Akana docs site).
DetailedAuditing
Provides detailed auditing of messages. Message metrics are recorded in the Usage Logs Analytics tab as well as the entire message for each exchange.
For full documentation about this type of policy, refer to: Using the Detailed Auditing Policy (Akana docs site).
Policy Category: Monitoring
OAuthSecurity
The OAuthSecurity Policy uses the OAuth configuration assigned to an API when enforcing OAuth tokens in the received request.
Note: If you're applying this policy, remember to also specify OAuth details for the API. On the API Details page, from the drop-down on the right, click OAuth Details.
For full documentation about this type of policy, refer to: Using the OAuth Security Policy (Akana docs site).
Policy Category: OAuth

For more information about policies, see Policy List.

Note: In some cases, such as an on-premise installation, the Site Admin has the ability to create and manage additional policies. In this scenario:

  • If you require a policy that isn't on the default list, ask the Site Admin.
  • If you see policies on the list that are not explained above, ask the Site Admin for information.

Back to top

Which policies should I choose?

Your selection of one or more policies for a specific API will be determined by the level of security required, whether monitoring is required, whether the API supports OAuth, and other factors.

If the API doesn't allow anonymous requests, you'll need to have the AtmosphereApplicationSecurityPolicy in place so that the API can authenticate app requests.

If the API allows anonymous requests, do not specify any policies.

Note: We don't recommend accepting anonymous requests. At minimum, particularly for a Live implementation, it's best to include at least the AtmosphereApplicationSecurityPolicy.

If you want to have monitoring for your API, choose one of the monitoring policies also.

If you want your API to support OAuth, enable the OAuthSecurity policy.

For more information about policies, see Policy List.

Back to top

How can I see details about a policy?

When you're adding policies to your implementation, you just see the policy title, not the details about how the policy is configured.

If you want to know more, you can click the title of the policy. Policy details are displayed in a pop-up window. This information is view-only; if you want any changes to the available policies, check with the Business Admin.

You can also review a brief description of the policy and click through for more details about each type of policy (see What security and monitoring policies are supported? above).

To view details for a policy
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the link for the implementation. The summary page for the implementation is displayed.
  4. In the Policies section, click Edit.
  5. Find the policy and click the policy icon. Policy details are displayed in a pop-up window.
  6. Change the policy assignments, if desired, or cancel out of the window.

Back to top

What is the minimum policy requirement for my API?

There is no minimum policy requirement for an API. However, it's best to at minimum select the AtmosphereApplicationSecurityPolicy, which gives you basic security.

If you want to see charts and logs, you must also select a monitoring policy.

Back to top

How do I assign policies to my API implementation?

Policy assignments are specific to an API version implementation. Follow the steps below.

To assign a policy to an API implementation
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to edit. The summary page for the implementation is displayed. There are several sections to the page:
    • General information about the implementation
    • Deployment zone data
    • Policies
    • Certificate
    • Resources
  4. In the Policies section, click Edit.
  5. In the Available Policies section, choose the policy you want to add and click Attach.
  6. Click Save.
To remove a policy from an API implementation
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation you want to edit. The summary page for the implementation is displayed. There are several sections to the page:
    • General information about the implementation
    • Deployment zone data
    • Policies
    • Certificate
    • Resources
  4. In the Policies section, click Edit.
  5. In the Attached Policies section, choose the policy and click Remove.
  6. Click Save.

Back to top

How do I see which policies are assigned to my API implementation?

When you assign policies to an API implementation, they're displayed in the summary view for the implementation, in the bottom section.

To see which policies are assigned to an API implementation
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation.
  4. In the Policies section of the page, review which policies are assigned. If needed, click Edit to change the policy assignments.

Back to top

How do I set up my API to support CORS?

If you want your API to support cross-origin resource sharing (CORS), you can do that in your API implementation in the platform.

In your API setup, choose the implementation and then add the CorsAllowAll policy.

When the API definition includes this policy, the proxy endpoint will accept request messages that come from a different domain, in the context of a browser.

Back to top

Managing Keys and Certificates for an API:

How do I manage keys and certificates for my API?

API Platform Version: 8.2

When you upload a private key and certificate for an API implementation, the key and certificate pair can be used for encrypting content for the API implementation through mechanisms such as:

You can manage trusted keys and certificates separately for each implementation, including uploading new certificates, uploading trusted certificates, downloading existing certificates, and assigning aliases.

The key is unique for each service identity (implementation).

The key/certificate must already be trusted. If it isn't yet trusted, ask the Policy Manager Admin to add it to the Trust Store.

Note: For information about setting up keys and certificates in Policy Manager, which includes the same functionality, see Managing Keys (Policy Manager documentation).

To manage keys and certificates for an API implementation
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Implementations.
  3. Click the implementation.
  4. In the Certificate section of the page, click Edit.
  5. On the Keys and Certificates page, choose one of these options:
  6. When done, click Save.
To upload a new private key and certificate for an implementation

Go to the Keys and Certificates for your implementation (see To manage keys and certificates for an API implementation above).

  1. Click Upload New.
  2. Browse for the file, such as a JKS file.
  3. Enter keystore password, key alias, and key password.
  4. Click Finish. The certificate details are displayed in the Keys and Certificates page.
  5. Click Go back to Implementation Details. The new certificate details are displayed on the Implementation Details page. An example is shown below.

    Certificate details for an implementation

To download a certificate for an implementation
  1. Go to the Keys and Certificates for your implementation (see To manage keys and certificates for an API implementation above). The existing certificate is displayed. An example is shown below.

    Keys and  Certificates page

  2. Click Download.
  3. Choose to open or save the certificate file.
To delete a trusted certificate for an implementation
  1. Go to the Keys and Certificates for your implementation (see To manage keys and certificates for an API implementation above).
  2. Click Delete.
  3. At the prompt, click OK to confirm the deletion.

Back to top

How does the platform support SNI?

API Platform Version: 8.2

When API transactions are sent to the Network Director using HTTPS, typically the Network Director uses the key and presents the certificate uploaded as part of the HTTPS listener configuration. In order to support different certificates based on the virtual host of an API, Server Name Indication (SNI) can be used. In this scenario, the key and certificate uploaded for an API can be used to negotiate with clients by specifying the virtual host of the API instead of the listener's key and certificate as part of the SNI extension.

If you want to use an API-specific security key/certificate, you'll need to:

  1. Create the key and certificate, which must meet certain conditions (see below).
  2. Upload the key and certificate to the platform.
  3. In the implementation, designate that you want to use the API-specific key and certificate.

For details, see How do I set up my API to support SNI? below.

Back to top

How do I set up my API to support SNI?

API Platform Version: 8.2

The API platform's support of SNI means that multiple keys/certificates can be used for one HTTPS endpoint. You can have individual identity keys/certificates per API implementation. Each implementation can use its own key/certificate for its own clients.

To use SNI, the deployment zone must support HTTPS, and you must complete these steps:

  1. When you create your key/certificate externally, make sure the subject common name (CN) field in the certificate matches the virtual host.

    Note: the platform also supports the use of subject alternate names in the certificate. If you are using a subject alternate name, the same constraint applies; the CN field must match the virtual host name.

  2. Upload the certificate to the API implementation. This is set up on the implementation page, in the Certificates section. See To upload a new private key and certificate for an implementation.
  3. In the implementation page, in the HTTPS tab for the deployment, check the Use Implementation's Key/Certificate for SSL option. See To edit an API's deployment zone assignment for a specific implementation.

Once these settings are in place, the platform uses the appropriate certificate based on the requested hostname.

Back to top