Adding an API

Add an API on the Akana API Platform.

API Platform Version: 8.1 and later

Table of Contents

  1. Add API: Overview
  2. Add API: Process Flow
  3. How do I add an API?
  4. What information do I need to add an API from scratch?
  5. What is the process flow to add an API by designing from scratch?
  6. How do I add an API by designing from scratch?
  7. What types of API description document can I use to define my API?
  8. What is the process flow to add an API using an API description document?
  9. Can I upload my API description in a ZIP file?
  10. How do I add an API using an API description document?
  11. What is the process flow to add an API from an existing service?
  12. How do I add an API from an existing service?
  13. What is the API pattern and which pattern should I choose?
  14. How do I add an implementation for an API?
  15. How do I add a SOAP-based API?
  16. How do I edit an API?
  17. How do I edit a SOAP-based API?
  18. How do I delete an API?
  19. How do I add an API version?
  20. How do I edit an API version?
  21. Should I allow anonymous access?
  22. Should I require approval for API access requests?
  23. Why would I use the platform to proxy my API?
  24. Does the platform support overloaded operations?
Import/Export:
  1. How do I export an API?
  2. What are the contents of the API export file?
  3. How do I import an API from an export file?

Add API: Overview

The Akana API Platform leads you through a simple, streamlined process for adding an API. It goes like this:

Create API process

For information about how to complete each of these steps, refer to:

If you want to create your API by importing an API description document such as a Swagger document, the process is even more streamlined:

Create API using description document

To get started, see How do I add an API? below.

Back to top

Add API: Process Flow

The process flow is a little different depending on how you add the API. For more information and process flow diagrams, choose the applicable link below:

Back to top

How do I add an API?

To add a complete API definition on the platform, you'll need to provide information about the API, either manually, by uploading an API description document, or by referencing an API already set up in the underlying infrastructure (API Gateway).

To get started immediately, you can simply name your API and save. You can go back and add more information later.

To get started adding an API (minimum steps)
  1. Click the plus sign (+) in the middle of the top menu bar, and choose Add a New API.
  2. Optional: click the advanced options icon on the right, and choose a different implementation pattern. Proxy is the default, but you can also choose Orchestration. For a tutorial video, see Add an API using orchestration (external link).
  3. Specify a name for the API, and click Save.

You can add the rest of the information later.

Probably, you'll want to be prepared with information about your API, so that you can set up all the information the platform needs, and you can then test. You have three choices:

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add API page. If so, these additional fields collect information about your API. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

Back to top

What information do I need to add an API from scratch?

You can create an API with just the name, then save it and add the rest later.

To complete the task, if you're adding a REST API from scratch, you'll need to be ready with the exact information for the API definition.

Make sure you have the exact spelling/wording, where applicable.

The specific information you'll need of course depends on your specific API, its definition and its level of complexity.

Ideal:

To provide full details of your API, that will enable your users to take full advantage of the rich features of Test Client and ensure your API's generated documentation is really complete and useful, you'll need to provide exact details of the following:

  • Operation definitions, including HTTP verb and URL
  • Parameters
  • Request headers
  • Request and response media types
  • Responses, including HTTP code and description
  • Model object definitions that are sent in the request and response
Bare minimum:

If you don't provide all of the above, your users will be missing out on the features of Test Client and the generated documentation. However, your API will still work as long as you provide the following:

  • URL path
  • HTTP verb
  • Request media types
  • Response media types

If you start defining your API and find you don't have all the information to hand, don't worry. You can save your work and come back to it later.

Back to top

What is the process flow to add an API by designing from scratch?

When you choose to add an API, and you don't have an API description document, you can define your API from scratch using the API Designer.

To fully design the API, you'll need to have your API documentation or other source of information handy so that you define the API accurately.

In API Designer, you can add operations, parameters, and media types, model objects, and any other information that's part of your API definition. For details, see Add or Modify an API Using API Designer.

Once that's done, you can create one or more implementations, add policy assignments, verify the access points, and test. The process flow is shown below.

Add API: from scratch

Back to top

How do I add an API by designing from scratch?

To add an API from scratch, it's best to first gather the information about the API definition. See What information do I need to add an API from scratch? above. You can save the API definition at any point, and come back to it later.

To add an API by designing from scratch
  1. Log in to the Akana API Platform.
  2. Click the plus sign (+) in the middle of the top menu bar, and choose Add a New API.
  3. Choose Add a new API and click Add.
  4. Click the I want to design my API from scratch (REST only) button.
  5. Provide a name for the API, and the endpoint if you have it already.
  6. Click Save. The platform saves the data and takes you to the API Designer for adding details about your API, including:
  7. When done, remember to click Save on the API Designer window, to save your API design.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add API page. If so, these additional fields collect information about your API. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

For more information about API Designer, see Add or Modify an API Using API Designer.

When your API design is complete, remember to test your API, using Test Client, to make sure it's working properly. See API Testing with Test Client.

If you need to change something later, you can edit the API definition as needed.

Back to top

What types of API description document can I use to define my API?

The platform supports adding an API by uploading, or otherwise referencing, API description documents in any of the following formats:

  • For REST APIs:
    • Swagger 2.0
    • Swagger 1.2
    • RAML 0.8
    • WADL
  • For SOAP APIs:
    • WSDL

Back to top

What is the process flow to add an API using an API description document?

When you choose to add a new API, you can then define your API by providing an API description document. The platform pulls all the information from the API description document and creates the API design and a Live implementation. You just need to add another implementation if needed, add or modify policy assignments, verify the access points, and test, as shown below.

Add API: from API description document

Back to top

Can I upload my API description in a ZIP file?

Yes. The file you upload can be an individual file or a ZIP file. However, you can only upload a ZIP file that's on your local filesystem, not via a URL.

If it is a ZIP file, it might include multiple services in one format; for example, several Swagger 2.0 documents. It might include a mix of Swagger versions, or a mix of different types of API description documents; for example, WADL and RAML or Swagger 2.0 and WSDL. If the file includes descriptions of more than one service, the platform displays a list of services so that you can choose the service to import for your API definition, as shown below.

Add API: list of services to import

Back to top

How do I add an API using an API description document?

To add an API using an API description document, first get the document, or make sure you know its location:

  • URL: an individual API description document. Make sure you have the full URL, with authentication credentials if needed.
  • File: an individual API description document file or a ZIP archive file containing one or more API description documents. Make sure the file is accessible on the local filesystem.

Follow the steps below.

To add an API using an API description document
  1. Log in to the Akana API Platform.
  2. Click the plus sign (+) in the middle of the top menu bar, and choose Add a New API.
  3. Choose Add a new API, and then click the I have a Swagger/RAML/WSDL/WADL document button. There are two ways you can provide the API definition:
    • URL: Provide the full URL, including protocol. If the URL requires authentication, provide your username and password (for Authentication Options, the default is Anonymous).
    • File: Browse to the location of the file and upload. If the file includes multiple services, you'll be shown a list of options for the service to import; choose the one you want.
  4. Click Save. The API is created, and the API's Overview page is displayed.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add API page. If so, these additional fields collect information about your API. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

When you create an API from an API description document, the platform automatically creates a Live implementation. You'll need to review the implementation and, probably, add policies. Optionally, you can also add a Sandbox implementation. For information about implementations, see Manage API Implementations.

When you're done, remember to test your API, using Test Client, to make sure it's working properly. See API Testing with Test Client.

Back to top

What is the process flow to add an API from an existing service?

When you specify an existing service, the platform pulls all the information already set up in the underlying infrastructure (API Gateway). You just need to add another implementation if needed, add or modify policy assignments, verify the access points, and test, as shown below.

Add API: from existing service

Back to top

How do I add an API from an existing service?

If you already have an API that's set up as a service in the API Gateway, or you want to create the service using the flexible service definition model offered by the API Gateway, you can use the Publish an existing service as an API option to add the API to the platform.

The platform references the information already set up in the API Gateway so you don't have to set up all the API details again.

You might choose this option if your service matches any of the following descriptions:

  • A virtual service that is an aggregate of different target services.
  • A virtual service that is implemented using an orchestration engine.
  • Any service that supports multiple interfaces and bindings.
  • A target service managed with any embedded agents, such as the J2EE Agent or DataPower Agent.
To add an API from an existing API Gateway service:
  1. Click the plus sign (+) in the middle of the top menu bar, and choose Add a New API.
  2. Choose Publish an existing service as an API and click Add. A wizard opens and displays at the first page, Details.
  3. Specify basic API details: Name, Description, Visibility, Version ID, and Version Description.
  4. Check the box to indicate whether the API uses licenses.
    For more information about setting up an API to use licenses, see How do I determine what licenses will be available for my API? For general information about the Licenses feature, see Licenses: Feature Overview.
  5. Optional: set up an avatar for your API. Click Upload and navigate to the avatar image file.
  6. Click Next to go to the Target API page.
  7. Set up the following values for at least one environment in which the API is running:
    • Service Key. Enter the environment name, unique service key, or URL. The platform locates the API Gateway service, and you can then select it. To locate the appropriate value, go to the API Gateway, open up the service, and click Edit. Copy the value and paste it into this field.
    • Allow anonymous access (yes/no)
    • Approval required (yes/no)
  8. Click Finish.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add API page. If so, these additional fields collect information about your API. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

Back to top

What is the API pattern and which pattern should I choose?

New in API Platform Version: 8.2

When you're adding an API, there are advanced options available to the right of the Add API page, as shown below.

Advanced Options

If you click the Advanced Options button, you'll see an additional field where you can determine the implementation pattern for the API. There are two choices, Proxy or Orchestration:

  • For a simple API that just references one endpoint, choose Proxy.

    In a proxy scenario, the API Implementation has a 1:1 relationship with a corresponding back-end Physical Service/API. The back-end Physical Service/API shares the same design as the API itself. A common use case is a scenario where you might want the platform to manage an existing API. In this scenario, you create a proxy and specify the existing API endpoint. The platform creates an API Implementation, automatically registers the appropriate back-end Physical Service/API, and creates default processes that tie each operation of the API Implementation to the appropriate back-end operation. The platform then provides a new (proxied) API endpoint that you can use and share for API access.

  • For a more complex API implementation, that might include one or more services, processes, or additional steps, choose Orchestration.

    In an orchestration scenario, you design the API and then manually build a mashup or orchestration for each operation of each implementation. You are free to call any number of other back-end Services/APIs in the orchestration. Unlike a proxy, where the platform automatically registers a back-end Physical Service/API and generates a default process for every operation, the orchestration simply creates an empty process. You can then edit each operation in turn and decide what kind of process you want and which back-end Services/APIs you want to invoke.

    An orchestration creates a service that is implemented with a process, rather than being simply a proxy of another service. If the API has an implementation pattern of Orchestration, you can access the Process Editor to manage the process for a specific operation by clicking through for that specific operation, at the bottom of the page for the specific implementation. This feature offers many additional capabilities for orchestrating processes relating to the API. For more information, see How do I manage orchestration for my implementation?

Back to top

How do I add an implementation for an API?

Your API implementation defines where the API is deployed.

When you create an API from an API description document, the platform automatically creates a Live implementation. Optionally, you can add a second implementation for Sandbox. You can also modify the implementation.

If you're creating your API from scratch, you'll need to create at least one implementation once you're done with the API design stage. See Add or Modify an API Using API Designer.

For information about adding and managing API implementations, see Manage API Implementations.

Back to top

How do I add a SOAP-based API?

If your API is SOAP-based, make sure you have the WSDL available; either a WSDL URL or an individual file or ZIP file.

Then, create your API following the procedure in How do I add an API using an API description document? above.

When you add an API based on a WSDL file, the summary of description languages displayed in the Implementations section at the bottom of the API Details page and the API Design page lists only WSDL, as shown below (Hermosa theme); you cannot view the API description in other API description languages such as Swagger and RAML, as you can for REST-based APIs.

Implementations bar for a SOAP API

In addition, you cannot edit the API design specifically. Instead, you'll need to upload a new WSDL file. See How do I edit a SOAP-based API? below.

For general information on the platform's support of API description languages, see API Description Language Support.

Back to top

How do I edit an API?

Once you've added an API, you might need to modify one or more aspects of the API, including:

To edit basic data about an API or API version
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Details. The summary of the API design is displayed on the Details page.
  3. In the top section, click Edit.
  4. Optional: on the left, modify any of these fields:
    • API name: A short and clear name to distinguish your API.
    • Summary: A short, plain-text field for internal display of the API description.
    • API Description: A concise description of the API that will attract users. Supports Markdown.
  5. Optional: on the right:
    • Change the parent organization by providing the new value in the Parent Organization Name field. Start typing the new organization name in the field. After the first three characters, the platform displays a list of matching organizations for you to choose from. For more information about organizations on the platform, see Organizations.
    • Click the blue dot to display advanced options and modify version number, version name, notes, tags, and/or visibility.
  6. Click Save.
To edit properties for an API or API version

Note: Properties may or may not be present, depending on the configuration of the developer portal.

  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Details. The summary of the API design is displayed on the Details page.
  3. In the Properties section, click Edit.
  4. Edit the properties as needed. For help, refer to field-level help if needed. If you need additional assistance, contact the Site Admin.
  5. Click Finish.

Back to top

How do I edit a SOAP-based API?

You can edit basic data about a SOAP-based API, such as name and description, in the same way as any other API; see To edit basic data about an API or API version.

To edit the properties for a SOAP-based API, you can't use the API Designer as you can with a REST-based API. However, you can update a SOAP API by uploading a revised WSDL file. Follow the steps below.

To update design information about a SOAP-based API or API version
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Details. The summary of the API design is displayed on the Details page.
  3. In the Design section, click Edit, as shown below, to access the Import Swagger/RAML/WSDL/WADL Document page.

    Editing a SOAP-based API

  4. Specify the URL for the WSDL file, providing credentials if needed; or choose File and upload an individual file or ZIP file.
  5. Click Save. The API is updated.

Back to top

How do I delete an API?

When you delete an API that has only one version, the API is deleted.

To delete an API
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Details.
  3. At the top right, click Delete.
  4. In the top section, click Edit. At the prompt, click OK. The API is deleted.

Note: If the API has more than one version, the API is not deleted until the last version is deleted.

Back to top

How do I add an API version?

You can have multiple versions for an API. One common use case is that the new version is being tested while the earlier version is servicing current traffic.

To add an API version
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Details. The summary of the API design is displayed on the Details page.
  3. From the drop-down menu at the top right, choose Add Version.
  4. At the Add API Version overlay, choose how you want to create the new version, and then click Add. In most cases you'd choose to create the new version the same way you created the API, but in some cases you might choose a different option. The choices are:
    • Add a new API: you'll need to provide the version name and specify whether you want to clone the current version, design from scratch, or import an API description document.
    • Publish an existing service as an API: specify version name and description, tags, visibility, and whether licensing is enabled for the API. Then specify the target API and click Finish.

If you choose Add a new API, you'll see the following additional choices on the Add API Version page:

  • Clone current version : Makes a copy of the current version. You can then go in and modify as needed.
  • I want to design this API version from scratch (REST only): allows you to design the API version from scratch. You can also:
    • Specify the API endpoint if you know it (for Proxy implementation pattern only).
    • Change the API pattern (implementation pattern).
  • I have a Swagger/RAML/WSDL/WADL document: If you choose this option, you can import an API description document for the API version.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add API Version page. If so, these additional fields collect information about your API version. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

Back to top

How do I edit an API version?

To edit API version information follow the steps covered in To edit basic data about an API or API version. Version information is in the Advanced options on the right; see Step 5 in the procedure.

Back to top

Should I allow anonymous access?

The Allow Anonymous Access option lets you enable or disable anonymous access to Sandbox and Live endpoints.

Allowing anonymous access to an API endpoint in a Sandbox implementation is useful if you want to offer a preview of an API to developers without requiring users to create an app or sign up to the platform. For example, if you have a specific feature set that you want to expose as part of promoting your API, you can expose those operations in your API configuration, and enable the Allow Anonymous Access option.

With anonymous access, developers can review your API documentation and try out the API without signing up and requesting access. If a developer tries out the API and likes it, he/she can then sign up, create an app on the platform, and request API access.

Your decision will depend on many factors including the nature of your app and your target audience.

We strongly recommend that you do not allow anonymous access to a Live implementation for security reasons. However, allowing anonymous access to a Sandbox implementation means that app developers can easily try out your API without having to set up an app on the platform.

Note that with anonymous access, viewing of metrics such as charts and logs is not supported.

Back to top

Should I require approval for API access requests?

Requiring approval for API access requests introduces a delay for app developers, but gives you the chance for manual intervention and gives you greater control.

One approach is to allow anonymous access, with no approval required, for a Sandbox implementation, but to require approval for access to a Live implementation.

In some cases, you might decide that even though you are allowing anonymous access to a Sandbox implementation, you'll still require approval for an API access contract. If the API allows anonymous access, app developers can access it without connecting the app to the API; however, unless there is a connection contract, the API doesn't show up in the app's Test Client for testing. For this reason, app developers might prefer not to take advantage of the anonymous access, but to request a contract instead, so that your API is available for selection in Test Client.

Even in this scenario, you might choose to allow anonymous access to the Sandbox implementation, not require approval for contracts in the Sandbox implementation, but require approval for contracts in the Live implementation. App developers could then request a contract in the Sandbox environment and would get immediate access to your API.

Back to top

Why would I use the platform to proxy my API?

When you set up your API on the platform, using the platform as a proxy, your API is the Target API and the platform is the Proxy API. This allows you to configure an endpoint in a particular environment (for example, internal or external network) that is accessible by your target applications.

A proxy API endpoint exists in the Cloud and is similar to a virtual service. Users access the proxy that runs in the Cloud, rather than accessing the API endpoint directly. Traffic is channeled via the proxy to your target API. This is more secure for your API. You can also use a vanity hostname, to make things easier for your users.

Advantages:

Internal / External Networks—If you want to access your real API on an internal network, but want to expose specific functionality on an external network, you can add the API Target URL using the Add a New API function, and then virtualize the API by specifying a Proxy API Target URL for specific functionality you want to make available on an external network.

Bridge Between App and Proxy API—If your API is focused on the business aspects of the API or service, you can set up the proxy API to provide other tasks such as security enforcement or specifications required by the target (for example, API specs for the app team).

Sandbox / Live Implementation Access—App developers can access either your Live implementation, Sandbox implementation, or both.

Contract Enforcement—If you configure your API with a proxy, you can take advantage of the platform's contract enforcement functionality. Here's how it works:

  • When you add an API to the platform your policy administrator adds a series of security policies to the Tenant Organization for your platform using the Akana Policy Manager Console. Site or Policy Administrators can refer to the Akana API Platform Installation Guide for more information. Email Technical Support for more information.
  • In the platform, apps that would like to have access to your API submit and API Access Request.
  • When the request is approved, the app is "connected" to the API.
  • The security policies are in force when the app is connected to the API and ensure that only authorized applications can gain access to your API at runtime.

Note: if your API is not configured with a proxy, you will need to provide your own firewall rules and security approach to restrict applications making calls to your API.

Back to top

Does the platform support overloaded operations?

The platform supports adding overloaded operations in API Designer. Overloaded operations are displayed in the generated Swagger documentation for the API via API > Documentation in the Akana API Portal.

However, the Swagger 2.0 standard specification does not support overloaded operations, so only one operation will show up in the generated API documentation. Also, if the Swagger documentation includes overloaded operations, the raw Swagger JSON is not available from API > Details > Implementations (bottom of page) > links to definition language (on the right). Instead, an error message is returned. The platform supports display of the generated swagger documentation to API users viewing API documentation via API >Document.

Back to top

Import/Export:

How do I export an API?

You can export information about an API to an external file. You can then import that file to another instance of the platform. One use of this feature is to move data from one environment to another, such as from a development environment to a testing or Live implementation.

You can also choose whether or not to export additional data associated with the API, such as policies, contracts, scopes, and documentation.

To export an API:
  1. Log in to the Akana API Platform and go to the overview page for your API.
  2. From the left menu bar, choose Details. The summary of the API design is displayed on the Details page.
  3. In the top section, click the drop-down, and choose Export.
  4. In the Export dialog, choose the versions you want to export (Current or All) and the options. If you want to export all information about the API, check all boxes. You can export the following data associated with the API:
    • Export Operational Policies
    • Export QoS Policies
    • Export API Administrators
      Note: the relationship of the user as an API admin is exported, but the user is not exported. The user must exist in the target environment. If the user does not exist when the information is imported, the API is created without that admin. From there, either a) the user can sign up and be invited to be an admin, b) the user can sign up and the API data can be reimported, c) another individual can be designated as an API admin.
    • Export API Implementation Services
      Note: If the API was created using an existing service, this option allows you to choose whether or not to export the API implementation services, as set up in Policy Manager. If the API was created as a new service, implementation services are always exported along with API.
    • Export API Contracts
    • Export Scopes
    • Export Resources/Documentation
    • Export API PKI
  1. Click Export.
  2. Choose to save or open the export file.

Back to top

What are the contents of the API export file?

The API export file includes all the core information about the API, as well as any of the optional additional information you specified.

The file has a very specific structure. It will look something like the image below:

File structure for an API export file

The export file will generally include the following:

  • Files at root level:
    • objectgraph.xml: An XML file that shows the relationships between resources.
    • objectdata.xml: An XML-based summary of all the data in the export file.
    • exportproperties.properties: a properties file showing which options were included in the export file.
  • bpels: a folder containing XML business process files (bpel files). One for each operation, for each environment. So, for example, if the API has five operations, and runs in Sandbox and Live implementations, there are 10 bpel files.
  • services: a folder containing a subfolder for each environment, each subfolder containing a bpel.xml file for the applicable service/environment.
  • wsdls: a folder containing WSDL files for the service.

Back to top

How do I import an API from an export file?

Once you've exported an API to an external ZIP file, it can be imported to another environment. For example, you can export from a development environment and then import to a testing or Live implementation.

The API Admin or Business Admin can export information about an API to an external file. However, only a Site Admin or Business Admin can import.

If you need help with import functions, contact your Administrator.

If you are an Administrator, refer to the Site Admin help.

Back to top