API Administration: Overview
Overview of API management in the Akana API platform.
API Platform Version: 8.1 and later
Table of Contents
- How do I add an API?
- How do I get started?
- What API management capabilities are available to the API Admin in the platform?
- What are the differences between the API Admin and Business Admin roles?
- How do I manage my API?
- What's the difference between the Overview page and the Details page?
- What are API properties?
- Related Topics
How do I add an API?
There are three approaches to adding an API in the platform.
Review the options in the table below to decide which is best for you. Then click through to the process overview and instructions.
|Use this option...||If...|
|Add a new API > Design from Scratch||
The API is not already set up as a service in the API Gateway, and you want to define it by hand rather than using an API description document.
|Add a new API > Swagger/RAML/WSDL/WADL document||
The API is not already set up as a service in the API Gateway, and you want to define it using an API description document.
|Publish an existing service as an API||
The API is already set up as a service in the API Gateway.
How do I get started?
The API development process steps you through the stages shown below: Add, Design, Implement, and Test.
To get started, click the plus sign (+) in the middle of the top menu bar, and choose Add a New API.
You can define your API from scratch, or you can import an API description document. Either way, you'll need to have your full API definition ready.
For more information about adding an API, see Add an API.
Once you've added the API, take a moment to review API management capabilities (What API management capabilities are available to the API Admin in the platform?) and how you get around in the user interface to complete these tasks (How do I manage my API?).
For some tutorial videos to help you get started, see Tutorial Videos.
What API management capabilities are available to the API Admin in the platform?
When a user creates an API, that user automatically becomes the first Admin for the API. All API Admins have the same rights. They can:
- Invite additional users to the API Admin group, or remove existing members from the team.
- Add and manage API implementations.
- Upload, modify, and delete API documentation.
- Upload legal agreements for the API.
- Manage an API Context Group, including creating the group, inviting one or more members, changing a member's role, and modifying or deleting the group.
- Invite independent groups to connect with the API.
- Manage API access requests including granting an app's request for API access and suspending/resuming or cancelling API access.
- Make changes to the API including modifying the API, adding, modifying, or deleting API versions, or deleting the API.
- View analytics for API performance, including monitoring volume and looking at detailed information about the messages being processed, such as headers.
- Change policies that are applied to the API.
- Modify the API, including changing the endpoint, operations, and other details associated with the API.
- Moderate user-generated content associated with the API, such as discussions, reviews, and comments. See Forum Moderation.
- Manage tickets associated with the API, including opening, modifying, closing, and deleting tickets and changing ticket status.
- Export API information.
For details and links, see How do I manage my API?
Note: If a Business Admin assigns a user the API Administrator role in the context of a business organization (see What are the default roles for the API platform: API Administrator), that role has full rights to view, add, modify, or delete an API, but does not have permission to view or modify the API Admin group. Only when a user creates the API, or is invited to the API Admin group, does the user have full rights both to the API and to the API Admin group.
What are the differences between the API Admin and Business Admin roles?
In a tenant scenario, a user who is a Business Admin for the tenant has full permission to all resources within the tenant business, including all apps and APIs.
The Business Admin has the same rights for all APIs as API Admins have for each API, plus additional rights and responsibilities.
How do I manage my API?
Once you've added your API, there are many steps you'll need to take to manage your API on a day to day basis, including such activities as adding other API Admins, testing the API, monitoring API analytics, and more.
For a summary of activities, see What API management capabilities are available to the API Admin in the platform?
From the point that you've successfully added the API, take a moment to look at the user interface and see the various pages where you can manage activities associated with your API. A sample API Overview page is shown below.
On the left menu bar, the following options allow you to perform activities associated with your API:
- Displays details about the current API design, including API design (Path, HTTP Verb, and Name for all operations) and Implementations (Name and Endpoints).
- Offers access to additional API setup steps such as setting up OAuth details and auto-connect settings, adding a version, and exporting the API information.
- Provides edit access to modify the API definition.
- Possibly, includes a Properties section. See What are API properties?
- Assign policies to the API or remove policies.
- Displays a summary of any existing implementations.
- Provides Add capability to define a new implementation.
- Provides Edit capability to edit an existing implementation.
- Allows you to review metrics for the API, such as charts and logs.
- Allows you to export metric information.
- Allows you to upload authored API documentation content and manage both generated and authored documentation.
- Displays generated API documentation for the API, if available.
- Displays authored API documentation for the API if it has been uploaded.
- Test Client:
- Allows you to test your API in the context of an app, or in an anonymous context (without any app) if the API supports anonymous access.
- Allows you to add headers and parameters, test with different OAuth versions, and view request and response information.
- Upload legal agreements for the API. Users requesting access to the API must accept the legal agreement as part of the API access process.
- Manage legal agreements (activate, deactivate).
- View existing legal agreements.
- Manage who can see the API (available only if the Licenses feature is enabled).
- Invite existing platform users, or new users, to be additional API Admins for the current API.
- Remove existing API Admins from the team.
- Displays information about the apps that are connected to the API, including the status of the connection.
- Displays a summary of users who are following the API.
What's the difference between the Overview page and the Details page?
The API Overview page is like your API's homepage in the developer portal; app developers can view this page to get information about your API and what it offers.
The API Details page is visible only to API Admins. This is a bit like a Dashboard for your API. From the top-level API Details page you can manage information about your API such as:
- Top section:
- Edit: Edit the basic API metadata (name, description, and avatar)
- Delete: Delete the API version. If there's only one version, this action deletes the entire API.
- Auto-Connect: Set up auto-connect settings for the API.
- OAuth Details: Set up information needed for your API to support OAuth.
- Manage Licensing: Set up information needed for your API to offer different licenses; for example, a limited license for access to GET resources and a full license for access to all resources.
- Add Version: Add a new version for the API.
- Export: Export information about the API to a ZIP file that can be imported to another instance of the API platform.
- Summary information is displayed about the API:
- On the left: Avatar, Type, and Tags
- On the right: API Description, Version, Version Notes, and Organization. You can click through to the Organization page.
- Middle section:
- View the design of your API, and click Edit to modify.
- Bottom section:
- View a summary of the implementations for your API.
The API Details options menu is shown below.
What are API properties?
In some cases, depending on platform configuration, some resources in the developer portal, such as apps and APIs, might include additional properties. If these exist, you'll see them when adding, editing, or viewing the resource.
For APIs, if this feature is in place, when you're adding the API you'll be asked for additional information, over and above what's covered in the standard help text. When you've created the API, you'll see a Properties section at the bottom of the API's Details page, displaying the values.
Properties may or may not be collected depending on how the developer portal is configured. You can also edit the properties; for more information, see To edit properties for an app version.
An example is shown below.
If API properties are in place, they appear in these pages:
- Add API (add properties)
- Add API Version (add properties)
- The API's Details page (view properties)
- The API's Details page, Properties section > Edit button > Properties page (edit properties)