LIST API REST API RESOURCE API

ROLE API

This page describes the K2HR3 ROLE API. The purpose of the ROLE API is to create and update and get and delete a K2HR3 ROLE. See the Basic Usage about the K2HR3 ROLE in the K2HR3.

POST(Create ROLE)

Creates a K2HR3 ROLE.

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Request Body

{
    role:    {
        name:        <role name or yrn full path>
        policies:    [
                         <policy yrn full path>,
                         ...
                     ]
        alias:       [
                         <role yrn full path>,
                         ...
                     ]
    }
}

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

PUT(Create ROLE)

Creates a K2HR3 ROLE.

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role?urlarg

Header

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

URL Arguments

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

POST(Add HOST to ROLE)

Adds a member(aka a hostname or an IP address) to a K2HR3 ROLE.

Endpoint(URL)

Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path

Role Token

http(s)://API SERVER:PORT/v1/role/yrn full path to role

Header

Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Role Token

API server will add a source IP address to a role if it finds a role token in request parameters.

Content-Type: application/json
x-auth-token: R=<Role Token>

Request Body

Scoped User Token

One request body includes only one host.

{
    host:    {
        host:            <hostname / ip address>
        port:            <port number>
        cuk:             <container unique key: reserved>
        extra:           <extra string data>
    }
    clear_hostname:      <true/false>
    clear_ips:           <true/false>
}

One request body includes multiple hosts.

{
    host:    [
        {
            host:        <hostname / ip address>
            port:        <port number>
            cuk:         <container unique key: reserved>
            extra:       <extra string data>
        },
        ...
    ]
    clear_hostname:      <true/false>
    clear_ips:           <true/false>
}

Role Token

{
    host:    {
        port:            <port number>
        cuk:             <container unique key: reserved>
        extra:           <extra string data>
    }
}

Parameters

Note: Port assignment

You need to pay special attention in case you add a hostname or IP address that already exists with a different port.

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

PUT(Add HOST to ROLE)

Adds a member(aka a hostname or an IP address) to a K2HR3 ROLE.

Endpoint(URL)

Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path?urlarg

Role Token

http(s)://API SERVER:PORT/v1/role/yrn full path to role?urlarg

Header

Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Role Token

API server will add a source IP address to a role if it finds a role token in request parameters.

Content-Type: application/json
x-auth-token: R=<Role Token>

URL Arguments

Scoped User Token

Role Token

Note

If you add a hostname or IP address that already exists with a different port, you should know the followings:

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

GET(Show ROLE details)

Shows details for a role.

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path?urlarg

Header

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

URL Arguments

Response status

200、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
    role:       {
        policies:   array,
        aliases:    array
        hosts: {
            hostnames: [
                "<hostname> <port> <cuk>",
                ...
            ],
            ips: [
                "<ip address> <port> <cuk>",
                ...
            ]
        }
    }
}

GET(Create ROLE Token)

Create a role token. Role API creates a role token in the following three cases.

Endpoint(URL)

A Scoped User Token

http(s)://API SERVER:PORT/v1/role/token/role path or yrn full role path

A Role Token

http(s)://API SERVER:PORT/v1/role/token/role path or yrn full role path

No Tokens

http(s)://API SERVER:PORT/v1/role/token/yrn full role path

Header

A Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

A Role Token

Content-Type: application/json
x-auth-token: R=<Role Token>

No Tokens

Content-Type: application/json

Response status

200、40x

Response Body(JSON)

{
    result:       <true/false>
    message:      <null or error message string>
    token:        <role token string>
    registerpath: <URI path for userdata API>
}

HEAD(Validate ROLE)

Validates the client’s source IP address, a scoped user token or a role token.

Endpoint(URL)

A Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path

A Role Token

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path

A No Tokens

http(s)://API SERVER:PORT/v1/role/yrn full role path

Header

A Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

A Role Token

Content-Type: application/json
x-auth-token: R=<Role Token>

No Tokens

Content-Type: application/json

Response status

204、40x

Response Body(JSON)

The server will not return a message-body in the response in the HEAD method.

DELETE(Delete ROLE)

Deletes a role, a hostname(or an IP address) from a role, a role token.

Note: Port assignment

You need to pay special attention in case you request to delete a hostname or IP address with a port.

This means that if an existing hostname or IP address with a port matches with requested hostname or IP address with a port port will be deleted.

Endpoint(URL)

A Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path?urlarg

A Role Token

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path

No Token

http(s)://API SERVER:PORT/v1/role/yrn full role path?urlarg

Header

A Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

A Role Token

Content-Type: application/json
x-auth-token: R=<Role Token>

No Token

Content-Type: application/json

URL Arguments

Scoped User Token(Delete ROLE)

A role identified by the scoped user token will be deleted if ROLE API find no URL args.

Scoped User Token(Delete Hostnames or IP addresses)

A Role Token

Empty

No Token

Response status

204、40x

Response Body(JSON)

Empty.

DELETE(Delete Hostname or IP address)

Delete an IP address(or a hostname).

In addition, to allow the specific role members to delete IP addresses, add the client host in ‘delhostrole’ role member. Make sure that the following settings exists in your K2HR3 API configuration file.

{
  'k2hr3admin': {
     'tenant':      'admintenant',
     'delhostrole': 'delhostrole'
  }
}

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role?urlarg

Header

Content-Type: application/json

URL Arguments

cuk

CUK(Cloud Unique Key = Instance ID), which is semantically same with OpenStack Instance ID, is required. You will find the ID in OpenStack Horizon UI. ROLE API will delete all IP addresses with the same CUK.

host

IP addresses in a JSON array object or in a string literal.

extra

openstack-auto-v1 It is currently a fixed value because We support ‘OpenStack’ only.

Response status

204、40x

Response Body(JSON)

Empty

LIST API REST API RESOURCE API