AAPF WebAPI Reference (1.5.4.0)

Download OpenAPI specification:Download

Introduction

AAPF WebAPI provides REST like APIs to control AAClusters.

This document describes the specifications of the apis and its usage.

How to use AAPF WebAPI

AAPF WebAPI can be called using XMLHTTPRequest (in AAPF WebUI) and any HTTP 1.1 Clients such as cURL.

Most of the apis require authentication before call these. We use the JSON Web Token (JWT) based authentication mechanism like OAuth 2.0.

For GUI/CUI application, do following to call apis for username and password based authentication:

Call /api/v1/login to authenticate user
/api/v1/login api returns two JWT when the authentication succeeded:
- Access Token
  - A token to identify who send HTTP requests
- Refresh Token
  - A token to refresh Access Token which is expired
Call the api that require authentication with Authorization: Bearer <Access Token> header
AAPF WebAPI Server verify the Access Token in Authorization header to authenticate the request
When the Access Token is expired, call /api/v1/access-token-refresh to get new Access Token

cURL Example:

#!/bin/bash
set -eu

#Get access token
auth_json=$(curl -v -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "localhost:3000/api/v1/login")
access_token=$(echo ${auth_json} | jq -r .accessToken)

#Call api
curl -v -X GET \
    -H "Authorization: Bearer ${access_token}" \
    "localhost:3000/api/v1/aaclusters"

For the command line tools, scripts and other applications, "AAPF API Token" should be used to call apis instead of Access Token. It's suitable for automated operation, calling apis from other application and calling apis from command line because AAPF API Token is never expired.

cURL Example:

#!/bin/bash
set -eu

api_token="<AAPF API Token>"

#Call api
curl -v -X GET \
    -H "Authorization: Bearer ${api_token}" \
    "localhost:3000/api/v1/aaclusters"

To get AAPF API Token, access the Manage AAPF API Tokens page in AAPF WebUI or use /api/v1/api-tokens api.

The error response will depend on the following HTTP status codes:

400 Bad Request for when the request was not processed, as the server could not understand what the client is asking for.
401 Unauthorized for when the request lacks valid credentials and it should re-request with the required credentials.
404 Not Found indicates that the requested resource was not found.
500 Internal Server Error indicates that the request is valid, but the server could not fulfill it due to some unexpected condition.

The error message is nothing more than reference information for the error code.

Authentication

AccessTokenAuth

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

Authentication APIs

These apis provide the authentication mechanism to identify users.

Login

Login to AAPF WebAPI Server.

Request Body schema: application/json

username required	string User name.
password required	string Password to login.

Responses

Request samples

Payload
bash

Content type

application/json

{"username": "user1",
"password": "passOfUser1"
}

Response samples

200
400
401

Content type

application/json

{"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ.LKKXIwAsehTHEPbUZ7iher9SEChc6z_ch2kNdeM1ABU",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicmVmcmVzaCIsImlhdCI6MTUxMDA0MjUwOSwiZXhwIjoxNTE1MjI2NTA5LCJ1c2VyIjp7InVzZXJuYW1lIjoidXNlcjEifX0.HCKU1_q9jZGnFjej8qXmxMt5PwWPSHq8vAJa36-iGyE"
}

Change password

Change user password.

This may return following errors:

The new password is too short.
The new password is same as the old one.
The oldpassword is wrong.

Authorizations:

AccessTokenAuth

Request Body schema: application/json

oldPassword required	string Old password
newPassword required	string New password

Responses

Request samples

Payload
bash

Content type

application/json

{"oldPassword": "user1pass",
"newPassword": "1234qwer"
}

Response samples

200
400
401

Content type

application/json

{"message": "Your password has been changed !"
}

Logout

Logout from AAPF WebAPI Server.

Authorizations:

AccessTokenAuth

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: logout.sh [access_token]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

if [ "$1" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$1"
fi

result=$(curl -v -X POST -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${access_token}" \
  "${AAWEB_ENDPOINT}/logout")

echo ${result} | jq . || echo ${result}

Response samples

200
401

Content type

application/json

{ }

Refresh Access Token

Refresh Access Token using Refresh Token.

Request Body schema: application/json

refreshToken

required

string

Refresh Token.

Responses

Request samples

Payload
bash

Content type

application/json

{"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicmVmcmVzaCIsImlhdCI6MTUxMDA0MjUwOSwiZXhwIjoxNTE1MjI2NTA5LCJ1c2VyIjp7InVzZXJuYW1lIjoidXNlcjEifX0.HCKU1_q9jZGnFjej8qXmxMt5PwWPSHq8vAJa36-iGyE"
}

Response samples

200
400
401

Content type

application/json

{"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ.LKKXIwAsehTHEPbUZ7iher9SEChc6z_ch2kNdeM1ABU"
}

AAPF API Token Management APIs

These apis provide the functions to manage AAPF API Tokens.

Get a list of AAPF API Tokens

Get a list of AAPF API Tokens which is owned by a request user. This list is ordered by the creation time.

Authorizations:

AccessTokenAuth

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: api_tokens_list.sh [access_token]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

if [ "$1" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$1"
fi

result=$(curl -v -X GET \
  -H "Authorization: Bearer ${access_token}" \
  "${AAWEB_ENDPOINT}/api-tokens")

echo ${result} | jq . || echo ${result}

Response samples

200
401

Content type

application/json

{"apiTokens": [{"tokenName": "APItoken1",
"createdAt": "2017-05-25T15:15:11.000000+09:00"
},
{"tokenName": "APItoken2",
"createdAt": "2017-10-30T12:24:36.000000+09:00"
}
]
}

Create a new AAPF API Token

Create a new AAPF API Token which is owned by a request user. When user enters a blank or duplicate name, it will return an error message.

Authorizations:

AccessTokenAuth

path Parameters

tokenName

required

string <= 512 characters

AAPF API Token name what user set before.

Request Body schema: application/json

password

required

string

User password

Responses

Request samples

Payload
bash

Content type

application/json

{"password": "passOfUser1"
}

Response samples

200
400
401

Content type

application/json

{"apiToken": {"tokenName": "APItoken",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ.LKKXIwAsehTHEPbUZ7iher9SEChc6z_ch2kNdeM1ABU",
"createdAt": "2017-05-25T15:15:11.000000+09:00"
}
}

Get information about an AAPF API Token

Get information about an AAPF API Token which is owned by a request user.

Authorizations:

AccessTokenAuth

path Parameters

tokenName

required

string <= 512 characters

AAPF API Token name what user set before.

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: api_token_info.sh tokenName [access_token]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

if [ "$2" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$2"
fi

if [ "$1" != "" ]; then
  result=$(curl -v -X GET \
    -H "Authorization: Bearer ${access_token}" \
    "${AAWEB_ENDPOINT}/api-tokens/$1")
else
  echo "Usage: api_token_info.sh tokenName [access_token]"
  exit 1
fi

echo ${result} | jq . || echo ${result}

Response samples

200
400
401
404

Content type

application/json

{"apiToken": {"tokenName": "APItoken",
"createdAt": "2017-05-25T15:15:11.000000+09:00"
}
}

Delete an AAPF API Token

Delete an AAPF API Token which is owned by a request user.

Authorizations:

AccessTokenAuth

path Parameters

tokenName

required

string <= 512 characters

AAPF API Token name what user set before.

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: api_token_delete.sh tokenName [access_token]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

if [ "$2" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$2"
fi

if [ "$1" != "" ]; then
  result=$(curl -v -X DELETE \
    -H "Authorization: Bearer ${access_token}" \
    "${AAWEB_ENDPOINT}/api-tokens/$1")
else
  echo "Usage: api_token_delete.sh token_id [access_token]"
  exit 1
fi

echo ${result} | jq . || echo ${result}

Response samples

200
400
401
404

Content type

application/json

{ }

AACluster Management APIs

These apis provide the functions to manage AAClusters.

Gets a list of AAClusters.

Gets a list of AAClusters which is owned by a request user. It is sorted by the cluster name.

If the request user has no AAClusters, returns an empty list:

{ aaclusters: [] }

Authorizations:

AccessTokenAuth

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: aacluster_list.sh [access_token]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

if [ "$1" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$1"
fi

result=$(curl -v -X GET \
  -H "Authorization: Bearer ${access_token}" \
  "${AAWEB_ENDPOINT}/aaclusters")

echo ${result} | jq . || echo ${result}

Response samples

200
401

Content type

application/json

{"aaclusters": [{"name": "sample",
"status": "created",
"services": [{"name": "jupyter-notebook",
"numberOfInstances": 1,
"instances": [{"index": 1,
"status": "ready",
"health": null,
"createdAt": "2017-08-01T01:55:59.474387+09:00",
"updatedAt": "2017-08-01T01:56:36.358779+09:00",
"url": "https://sample.aapf.com/proxy/abcdefg123/jupyter",
"urlPath": "/proxy/abcdefg123/jupyter",
"jupyterToken": "c6db3a7b715b04402b6a241faa6cf16274403bf50a7bbf91"
}
],
"image": {"repositoryName": "aa_jupyter_notebook",
"displayName": "Jupyter Notebook",
"description": "Standard Jupyter Notebook image provided by AAPF."
},
"perfType": {"name": "fixed-instance-small",
"displayName": "Fixed Instance(small)",
"resources": {"cpu": 0.5,
"memory": 1024,
"nvidia.com/gpu": null
}
},
"alerts": [ ]
},
{"name": "spark-master",
"numberOfInstances": 0,
"instances": [ ],
"image": { },
"perfType": { },
"alerts": [ ]
},
{"name": "spark-worker",
"numberOfInstances": 0,
"instances": [ ],
"image": { },
"perfType": { },
"alerts": [ ]
}
],
"createdAt": "2017-08-01T01:57:02.401372+09:00"
}
]
}

Gets information of an AACluster.

Gets information of an AACluster which is owned by a request user.

Authorizations:

AccessTokenAuth

path Parameters

nameOfAACluster

required

string <= 512 characters

The name of the AACluster.

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: aacluster_get.sh [cluster_name [access_token]]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

CLUSTER_NAME=${1:-sample}
if [ "$2" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$2"
fi

result=$(curl -v -X GET \
  -H "Authorization: Bearer ${access_token}" \
  "${AAWEB_ENDPOINT}/aaclusters/${CLUSTER_NAME}")

echo ${result} | jq . || echo ${result}

Response samples

200
400
401
404

Content type

application/json

{"aacluster": {"name": "sample",
"status": "created",
"services": [{"name": "jupyter-notebook",
"numberOfInstances": 1,
"instances": [{"index": 1,
"status": "ready",
"health": null,
"createdAt": "2017-08-01T01:55:59.474387+09:00",
"updatedAt": "2017-08-01T01:56:36.358779+09:00",
"url": "https://sample.aapf.com/proxy/abcdefg123/jupyter",
"urlPath": "/proxy/abcdefg123/jupyter",
"jupyterToken": "c6db3a7b715b04402b6a241faa6cf16274403bf50a7bbf91"
}
],
"image": {"repositoryName": "aa_jupyter_notebook",
"displayName": "Jupyter Notebook",
"description": "Standard Jupyter Notebook image provided by AAPF."
},
"perfType": {"name": "fixed-instance-small",
"displayName": "Fixed Instance(small)",
"resources": {"cpu": 0.5,
"memory": 1024,
"nvidia.com/gpu": null
}
},
"alerts": [ ]
},
{"name": "spark-master",
"numberOfInstances": 0,
"instances": [ ],
"image": { },
"perfType": { },
"alerts": [ ]
},
{"name": "spark-worker",
"numberOfInstances": 0,
"instances": [ ],
"image": { },
"perfType": { },
"alerts": [ ]
}
],
"createdAt": "2017-08-01T01:57:02.401372+09:00"
}
}

Creates a new AACluster.

Creates a new AACluster which is owned by a request user.

Authorizations:

AccessTokenAuth

path Parameters

nameOfAACluster

required

string <= 512 characters

The name of the AACluster.

Request Body schema: application/json

required

object

The parameters of service instances for the Jupyter Notebook

Responses

Request samples

Payload
bash

Content type

application/json

{"jupyterNotebook": {"image": {"repositoryName": "aa_jupyter_notebook"
},
"perfType": "small"
}
}

Response samples

202
400
401

Content type

application/json

{"message": "Accepted creating AACluster named 'sample'."
}

Deletes an AACluster.

Deletes an existing AACluster which is owned by a request user.

Authorizations:

AccessTokenAuth

path Parameters

nameOfAACluster

required

string <= 512 characters

The name of the AACluster.

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: aacluster_delete.sh [cluster_name [access_token]]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

CLUSTER_NAME=${1:-sample}

if [ "$2" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$2"
fi

curl -v --no-buffer -X DELETE \
  -H "Authorization: Bearer ${access_token}" \
  "${AAWEB_ENDPOINT}/aaclusters/${CLUSTER_NAME}" | jq .

Response samples

202
400
401
404

Content type

application/json

{"message": "Accepted deleting AACluster named 'sample'."
}

Performance Type Management APIs

These apis provide the functions to manage performance type.

Gets a list of performance types.

Gets a list of performance types. It is sorted by the name.

If there is no performance type, returns an empty list:

{ perfTypes: [] }

Authorizations:

AccessTokenAuth

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: perf_type_list.sh [access_token]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

if [ "$1" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$1"
fi

result=$(curl -v -X GET \
  -H "Authorization: Bearer ${access_token}" \
  "${AAWEB_ENDPOINT}/perf-types")

echo ${result} | jq . || echo ${result}

Response samples

200
401

Content type

application/json

{"perfTypes": [{"name": "0010_micro",
"displayName": "Micro (Fixed Performance)",
"resources": {"cpu": 0.25,
"memory": 512,
"nvidia.com/gpu": null
}
}
]
}

Image Management APIs

These apis provide the functions to manage images.

Gets a list of available images

Gets a list of available images. It is sorted by the repository name.

If there is no available images, returns an empty list:

{ images: [] }

Authorizations:

AccessTokenAuth

Responses

Request samples

bash

#!/bin/bash -eu
# Usage: image_list.sh [access_token]
AAWEB_ENDPOINT=${AAWEB_ENDPOINT:=localhost:3000/api/v1}

if [ "$1" == "" ]; then
  auth_json=$(curl -X POST -H 'Content-Type: application/json' \
    -d '{ "username": "user1", "password": "user1pass" }' \
    "${AAWEB_ENDPOINT}/login")
  access_token=$(jq -r .accessToken <(echo ${auth_json}))
else
  access_token="$1"
fi

result=$(curl -v -X GET \
  -H "Authorization: Bearer ${access_token}" \
  "${AAWEB_ENDPOINT}/images")

echo ${result} | jq . || echo ${result}

Response samples

200
401

Content type

application/json

{"images": [{"repositoryName": "aa_jupyter_notebook",
"displayName": "Jupyter Notebook",
"description": "Standard Jupyter Notebook image provided by AAPF."
}
]
}