Akana API Platform API: Overview
The Akana API Platform API is a REST-based API that supports activities relating to setting up, managing, and supporting app and API owners and all other platform users.
It has many features and capabilities to support such activities as logging in and out, setting up apps and APIs, creating contracts between apps and APIs, creating discussions and reviews, commenting on discussions and reviews, creating and managing groups such as app teams and API Scope Groups, and many others.
This documentation includes information on each operation that's available including parameters, possible values, and in most cases examples of requests and responses in JSON, XML, or plain text as applicable.
The documentation also includes various reference topics to help you with additional information on a range of subjects including workflows, roles, security, RSS channels, metrics, and many others. For a full list of topics, see Akana API Platform API Reference Material.
This topic includes:
- Services and Operations (Methods)
- Getting Started
- Using the API to Modify the Platform
- Tips on using the API
Services and Operations (Methods)
The Akana API Platform API services are summarized in the list below, with a link to detailed information about the operations available in each service.
Getting Started
To get started with using the Akana API Platform API, follow the steps below.
- Decide which services you need to use, and which methods (operations).
- Make sure the platform that your application is on (for example, .NET, iOS, or Android) supports the following:
- Cookies
- HTTP 1.1 protocol
- HTTP GET, POST, PUT, and DELETE operations
- Check whether any authentication is required. This depends on the specific API operation.
Note: If you are invoking any Akana API Platform operation that requires authentication, you must first invoke the login API POST /api/login) to get the authentication token. Once you have that, you can use it to invoke the other operations. The token is only valid for 30 minutes, so the application that's invoking the Akana API Platform operation must renew the token, or get a new token, periodically.
- For each operation, refer to the documentation for detailed information about the request message format and expected response.
Note: Remember that if parameter values contain special characters, they must be encoded. For example, if a parameter includes an email address, the @ sign must be replaced with its URL-encoded representation of %40. A space in a value must be encoded with %25, and so on.
Additional resources for getting started:
- For more detailed information about logging in and managing the session cookie, refer to Authentication and Security with the Akana API Platform API.
- For some example "getting started" scenarios, see "how-to" topics.
Using the API to Modify the Platform
You can use the Akana API Platform API to help speed up tasks normally completed through the Akana API Platform user interface, such as setting up your apps or APIs.
However, if you're running the API to make changes to the Akana API Platform user interface it's very important that you check for successful results along the way, and that if necessary you undo actions that haven't successfully completed. You must make sure you restore the user interface to a good stable condition with regard to your data.
When you're done, remember to invoke the POST /api/login/logout API to log out.
Tips on using the API
Some tips when using the API:
- When composing JSON content for POST or PUT operations, if you are not providing values, don't include empty parameters. Instead, leave the parameter out of your content entirely. If a value isn't required, you don't need that parameter in your content. Don't include empty strings.
- If you get an error, check the errors section for information. For every operation, the documentation includes a table at the bottom of the page listing some errors you might encounter; for example, a 404 if you forgot to include a required header.
