a9s Public API

This section describes how to use the a9s Public API to interact with your Service Instance through the available endpoints.

a9s Public API Versions

At the time of writing, there are 2 versions available of the a9s Public API: API V0 and API V1. As API V0 is deprecated, and will be discontinued in future releases, please consider using the endpoints of API V1 instead.

How to Access the API Using cURL

We run the a9s Public API protected by the a9s SSO Proxy. This means that in order to access this API, we need to be authenticated and authorized first, to access it.

Authentication

To correctly authorize the request when accessing using cURL, the user must first get the token from Cloud Foundry:

bearer_token=$(cf oauth-token | grep bearer)

Then, get the a9s Service Dashboard URL using cf service:

$ cf service <service_name>

This should give you an output like:

Showing info of service my-service in org example / space example as admin...

name:            my-service
service:         a9s-redis
[...]
dashboard:       https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d

Showing status of last operation from service my-service...

status:    create succeeded
[...]

Path Differences between API V0 and API V1

While in API V0 the URL can be used directly, when using API V1 the path has to be modified in order for the cURL command to work. This is done by replacing the current base path /service-instanceswith the base path /v1/instances; while the scheme, host, and service instance id remain the same.

Using the example above, the URL for API V0:

url="https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d"

While for API V1, the URL ends up looking like this:

url="https://a9s-redis-dashboard.example.com/v1/instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d"

Authorization

The user must execute the following command with the given Cloud Foundry token and a9s Service Dashboard URL, and then it creates the cookie authorized to be used in future API requests.

curl --cookie session.cookie --cookie-jar session.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" "${url}"

• Remember to use --location, since the a9s SSO Proxy redirects to the real endpoint.
• Use --insecure only, if running the Service Instance with self generated certificates.
• Use --cookie-jar to store the authorized cookie in a file to be used in future API requests.

The authentication is handled by Cloud Foundry, so when you have a valid token, you are authenticated. With this token, the a9s SSO Proxy checks if you are authorized to access the a9s Service Dashboard for the given instance.

Once the user is authorized, this information is stored in the session, which is then stored in the cookie. After this, the requests can be redirected to the a9s Public API and the user can access all the provided endpoints as described below.

info

This authorization step must be done before the API request when the user is not authorized yet.

Headers

The following HTTP Headers are defined for the operations on this API:

Header	Type	Description
Authorization*	string	A token that is authorized to access the a9s Public API for the given Service Instance.

* Headers with an asterisk are required.

Available Endpoints

As mentioned above, at the moment the a9s Public API has two versions running concurrently. And while both versions are fully functional, please note that a9s Public API V0 is deprecated. Thus, we recommend that you prefer the usage of the endpoints of a9s Public API V1 over a9s Public API V0.