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)

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.

Service Name Service Name Service Name
Alerts Dropbox Reviews
APIs Groups Roles
Apps Index Administration Search
Boards Legals Search Index
Businesses Licenses Tags
Client Services Login Tenant Administration
Console Resources Models Tenant Management
Content Notifications Tickets
Contracts Password Management UI Application
Deployment Zones PKI Keys Assignment Users
Discussions Policies Workflow
Domain Groups and User Management Properties  

Getting Started

To get started with using the Akana API Platform API, follow the steps below.

  1. Decide which services you need to use, and which methods (operations).
  2. 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
  3. 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.

  4. 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.

Invoke an API Operation using the Authentication Token

The authorization request header is used to provide credentials to authenticate an API. To authenticate requests, the API uses tokens in the Authorization header. Instead of using a Basic authentication (HTTP) that requires a user to provide a valid username and password to authenticate an API request, you can use the following two types of authentication tokens:

The Authorization header includes the authorization scheme and the authorization value. To pass the token for authorization, you must define:

  • The Authorization header value to AtmosphereUser {{AtmoAuthToken}} or X-Csrf-Token_{fedmemberID}
  • The token value to be used for authentication

The following is an example of an AtmoAuthToken:

POST /api/groups HTTP/1.1
Host: {hostname}
Accept: application/json
Content-Type: application/json
Authorization: AtomsphereUser TokenID%3Dcd36a4bd-e600-4e99-961a-c4ca0cfc93cd%2Cclaimed_id%3Durn%3Aatmosphere%3Auser%3Aacmepaymentscorp%3A14b1902f-3dfc-43e3-b09a-81137f091b96%2CissueTime%3D1614802132363%2CexpirationTime%3D1614803992357%2C...

The following is an example of an X-Csrf-Token_{fedmemberID} header:

POST /api/apis/versions/ff46365a-ebac-4fd3-9cbd-f1ac20262f80.acmepaymentscorp/legals HTTP/1.1
Host: {hostname}
Accept: */*
Content-Type: application/json; charset=UTF-8
X-Csrf-Token_acmepaymentscorp: TokenID%3D8ed70a13-8469-11e8-b37a-b155e4eabeb8%2CexpirationTime%3D153...

The acquired token can be used in the request's authorization header for the successful authentication of an API. The token presented is verified and then granted access to the API, returning the response that made the request.

Additional resources for getting started:

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.