1.1. API Common information

Following knowledges are required in common to use SSS API.

API Common info

What is “API”

Smart Data Platform API is a set of HTTP request / response to control your Smart Data Platform resources. Here “resources” includes not only Virtual Machine, Network, but includes your own user, tenant, contract itself.

In following chapters, we describe general usage of Smart Data Platform APIs.

What is “SSS”

SSS is a service conponent in Smart Data Platform, it provides some APIs to control your

  1. Contract: Smart Data Platform is a unit of billing. Each tenant, user, and other resource. belong to contract, and each contract can have separate billing address.
  2. Tenants: Tenant is a “box” which your computing resources belong.
  3. Users: User is a unit of authentication / authorization. Each user has itown API key / API sercret, and login id and password.
  4. Role: Tenant accessibility of each user for each tenant.
  5. API keys (and permissions): Set of strings which identifies / authenticates who you are in API request.

Get API Key / API Secrets

First of all, you have to get your own API key and API secret from SSS control panel to use API. Login to Enterprise Cloud 2.0, and access to “Profile” in header.

Access to "User" menu

Then you can see “API key” and “API secret key” in the next screen.

API key and API secret

Note these two strings to use in the following steps, and you also can transit API Reference top page. You can check all Smart Data Platform endpoints in API Reference top page.

You can access to all ECL2.0 services’ API of any region with this api key pair.

For Example,this endpoint depends on your contract’s default region. Default is “jp1”. “https://sss-[region]-ecl.api.ntt.com:443/api

You can use SSS API if you send to SSS in other regions, but some parameters will not be returned in that case.

Get Tenant ID

You have to specify tenant id (or tenant name) to control computing resources via API. You can your tenants’ id / name in this page of SSS control panel.

../../_images/get_tenant_id.png

(This procedure is required only when you are using APIs for contorolling tenant resources. You don’t need to specify tenant when you are using SSS API.)

Get Token from Keystone (API Authentication)

Most of Smart Data Platform API requires authentication with “Keystone”, which is API authenticator defaults to Openstack (Some service in Smart Data Platform have its own authentication).

Keystone requires “API key” and “API secret”, and “tenant id” or “tenant name” you are to control.

Following sample shows request sample of Keystone authentication.

curl -i \
-H "Content-Type: application/json" \
-d '
{
  "auth": {
      "identity": {
          "methods": [
              "password"
          ],
          "password": {
              "user": {
                  "domain": {
                      "id": "default"
                  },
                  "name": "wyH83LnfldskJFHlsejlsdFDM1",
                  "password": "yWBJfFfpHn932NZ"
              }
          }
      },
      "scope": {
          "project": {
              "id": "283f987b547f4f769904b1ae80f67c20"
          }
      }
  }
}' \
https://keystone-jp1-ecl.api.ntt.com/v3/auth/tokens

(“project” is the same meaning to “tenant” in Openstack)

Tenant id/name is not required for using SSS API. In this case you can simply omit “scope” object from json body.

curl -i \
-H "Content-Type: application/json" \
-d '
{
  "auth": {
      "identity": {
          "methods": [
              "password"
          ],
          "password": {
              "user": {
                  "domain": {
                      "id": "default"
                  },
                  "name": "wyH83LnfldskJFHlsejlsdFDM1",
                  "password": "yWBJfFfpHn932NZ"
              }
          }
      }
  }
}' \
https://keystone-jp1-ecl.api.ntt.com/v3/auth/tokens

Response should includes:

  • “X-Subject-Token” in header
  • JSON body (your role, tenant information, list of service endpoints)

if your name / password / tenant id (or tenant name) is collect.

X-Subject-Token is a essential information for API authentication, and you use this string in following steps. (We call this string just “token” after here.)

Obtained token lifetime is 1 hour.


Keystone is allocated in each region, so if you are trying to use regional services, you need to get token from a Keystone which the service belongs.

Usually, you can use jp1 APIs endpoint only. If you want to use other endpoints, please execute folowing.

  • The case you are admin user, please create the region’s tenant with jp1 SSS API endpoint.
  • The case you are not admin user, please ask to the admin user to create role between you and the region’s tenant.

Keystone API endpoint is expressed as

"keystone-{region name}-ecl.api.ntt.com"

For example,

"keystone-jp1-ecl.api.ntt.com"

is a Keystone URL for “jp1” region.

When you need to use services in “uk1” region, you have to get token from

"keystone-uk1-ecl.api.ntt.com"

instead.

Note

In following sections, we describe SSS API as example. See other documents for other service components’ API.

SSS API Endpoints

Smart Data Platform SSS API endpoint is described as:

https://sss-[region_name]-ecl.api.ntt.com/api

If SSS you are mainly using is “jp1.ecl.ntt.com” (this depends on your contract country, defalut is “jp1”), request URL should be like:

https://sss-jp1-ecl.api.ntt.com/api

Which ever SSS endpoint you use, you need to get token from the same region. This means

https://sss-jp1-ecl.api.ntt.com/api/v1.0/{resource}

receives token issued from

https://keystone-jp1-ecl.api.ntt.com/v3/

and

https://sss-uk1-ecl.api.ntt.com/api/v1.0/{resource}

receives token issued from

https://keystone-uk1-ecl.api.ntt.com/v3/

As SSS data is synced all over the world, any region endpoint can be used for most of SSS API, but some “regional” data includes in response from the contract’s default region.

SSS API Request Example

Once you determine SSS api endpoint, you can throw request.

  • SSS API is standard REST API, which uses json body as request / response.
  • Designate “X-Auth-Token” in header and set the token you got as value
  • TLS 1.0/1.2 algorithm is recommended for HTTP secure protocol.
  • For POST / PUT (requires body) request, set “Content-Type: application/json” in header

GET request example

curl -1 -iv -X GET -H"X-Auth-Token: 0a07185f627142fbba2f9a4b53c99015" https://sss-jp1-ecl.api.ntt.com/api/v1.0/tenants

POST request example

curl -1 -iv -X POST -H"Content-Type: application/json" -H"X-Auth-Token: 0a07185f627142fbba2f9a4b53c99015" -d '{
 "login_id": "some_login",
 "mail_address": "test@ntt.com",
 "password": "StrongPassword123!",
 "notify_password": "false"
}' https://sss-jp1-ecl.api.ntt.com/api/v1.0/users