The Tricircle Admin API

This Admin API documentation describes the ways of interacting with the Tricircle service via HTTP protocol using Representational State Transfer(ReST).

API Versions

In order to bring new features to users over time, versioning is supported by the Tricircle. The latest version of the Tricircle is v1.0.

The Version APIs work the same as other APIs as they still require authentication.

GET

GET

/

/{api_version}

List All Major versions

Show Details of Specific API Version

Service URLs

All API calls through the rest of this document require authentication with the OpenStack Identity service. They also require a base service url that can be got from the OpenStack Tricircle endpoint. This will be the root url that every call below will be added to build a full path.

For instance, if the Tricircle service url is http://127.0.0.1/tricircle/v1.0 then the full API call for /pods is http://127.0.0.1/tricircle/v1.0/pods.

As such, for the rest of this document we will leave out the root url where GET /pods really means GET {tricircle_service_url}/pods.

Pod

A pod represents a region in Keystone. When operating a pod, the Tricircle decides the correct endpoints to send request based on the region of the pod. Considering the architecture of the Tricircle, we have two kinds of pods: pod for central Neutron and pod for local Neutron.

GET

/pods

Retrieve Pod List

This fetches all the pods, including pod for central Neutron and pod(s) for local Neutron.

Normal Response Code: 200

Response

Pods contains a list of pod instances whose attributes are described in the following table.

Name

In

Type

Description

pod_id

body

string

pod_id is a uuid attribute of the pod object.

region_name

body

string

region_name is specified by user but must match the region name registered in Keystone.

az_name

body

string

When az_name is empty, it means this is a pod for central Neutron. If az_name is not empty, it means the pod will belong to this availability zone. Multiple pods with the same az_name means that these pods are under the same availability zone.

pod_az_name

body

string

pod_az_name is the az name used in the pod for local Neutron when creating network, router objects. It could be empty. If it’s empty, then no az parameter will be added to the request forwarded to the pod for local Neutron. If the pod_az_name is different from az_name, then the az parameter will be replaced with the pod_az_name when the request is forwarded to relevant pod for local Neutron.

dc_name

body

string

dc_name is the name of the data center where the pod is located.

Response Example

This is an example of response information for GET /pods.

{
    "pods": [
       {
            "dc_name": "",
            "pod_az_name": "",
            "pod_id": "1a51bee7-10f0-47e8-bb4a-70f51394069c",
            "az_name": "",
            "region_name": "RegionOne"
        },
        {
            "dc_name": "",
            "pod_az_name": "",
            "pod_id": "22cca6ad-b791-4805-af14-923c5224fcd2",
            "az_name": "az2",
            "region_name": "Pod2"
        },
        {
            "dc_name": "",
            "pod_az_name": "",
            "pod_id": "3c22e5d4-5fed-45ed-a1e9-d532668cedc2",
            "az_name": "az1",
            "region_name": "Pod1"
        }
    ]
}

GET

/pods/{pod_id}

Retrieve a Single Pod

This fetches a pod for central Neutron or a pod for local Neutron.

Normal Response Code: 200

Request

Name

In

Type

Description

pod_id

path

string

pod_id is a uuid attribute of the pod object.

Response

Here are two kinds of pods, including pod for central Neutron and pod for local Neutron. az_name is one of its attributes. A pod with empty az_name is for central Neutron, otherwise a pod with az_name specified is for local Neutron. All of its attributes are described in the following table.

Name

In

Type

Description

pod_id

body

string

pod_id is a uuid attribute of the pod object.

region_name

body

string

region_name is specified by user but must match the region name registered in Keystone.

az_name

body

string

When az_name is empty, it means this is a pod for central Neutron. If az_name is not empty, it means the pod will belong to this availability zone. Multiple pods with the same az_name means that these pods are under the same availability zone.

pod_az_name

body

string

pod_az_name is the az name used in the pod for local Neutron when creating network, router objects. It could be empty. If it’s empty, then no az parameter will be added to the request forwarded to the pod for local Neutron. If the pod_az_name is different from az_name, then the az parameter will be replaced with the pod_az_name when the request is forwarded to relevant pod for local Neutron.

dc_name

body

string

dc_name is the name of the data center where the pod is located.

Response Example

This is an example of response information for GET /pods/{pod_id}.

{
    "pod": {
        "dc_name": "",
        "pod_az_name": "",
        "pod_id": "3c22e5d4-5fed-45ed-a1e9-d532668cedc2",
        "az_name": "az1",
        "region_name": "Pod1"
    }
}

POST

/pods

Create a Pod

This creates a pod for central Neutron or a pod for local Neutron.

Normal Response Code: 200

Request

Some essential attributes of the pod instance are required and described in the following table.

Name

In

Type

Description

region_name

body

string

region_name is specified by user but must match the region name registered in Keystone.

az_name

body

string

When az_name is empty, it means this is a pod for central Neutron. If az_name is not empty, it means the pod will belong to this availability zone. Multiple pods with the same az_name means that these pods are under the same availability zone.

pod_az_name

body

string

pod_az_name is the az name used in the pod for local Neutron when creating network, router objects. It could be empty. If it’s empty, then no az parameter will be added to the request forwarded to the pod for local Neutron. If the pod_az_name is different from az_name, then the az parameter will be replaced with the pod_az_name when the request is forwarded to relevant pod for local Neutron.

dc_name

body

string

dc_name is the name of the data center where the pod is located.

Response

An id is assigned to a pod instance when it’s created. All of its attributes are listed below.

Name

In

Type

Description

pod_id

body

string

pod_id is automatically generated when creating a pod

region_name

body

string

region_name is specified by user but must match the region name registered in Keystone.

az_name

body

string

When az_name is empty, it means this is a pod for central Neutron. If az_name is not empty, it means the pod will belong to this availability zone. Multiple pods with the same az_name means that these pods are under the same availability zone.

pod_az_name

body

string

pod_az_name is the az name used in the pod for local Neutron when creating network, router objects. It could be empty. If it’s empty, then no az parameter will be added to the request forwarded to the pod for local Neutron. If the pod_az_name is different from az_name, then the az parameter will be replaced with the pod_az_name when the request is forwarded to relevant pod for local Neutron.

dc_name

body

string

dc_name is the name of the data center where the pod is located.

Request Example

This is an example of request information for POST /pods.

{
    "pod": {
        "region_name": "Pod3",
        "az_name": "az1",
        "pod_az_name": "az1",
        "dc_name": "data center 1"
    }
}

Response Example

This is an example of response information for POST /pods.

{
    "pod": {
        "dc_name": "data center 1",
        "pod_az_name": "az1",
        "pod_id": "e02e03b8-a94f-4eb1-991e-a8a271cc2313",
        "az_name": "az1",
        "region_name": "Pod3"
    }
}

DELETE

/pods/{pod_id}

Delete a Pod

This deletes a pod for central Neutron or a pod for local Neutron from availability-zone.

Normal Response Code: 200

Request

Name

In

Type

Description

pod_id

path

string

pod_id is a uuid attribute of the pod object.

Response

There is no response. But we can list all the pods to verify whether the specific pod has been deleted or not.

Resource Routing

The Tricircle is responsible for resource(for example, network, subnet, port, router, etc) creation both in local Neutron and central Neutron.

In order to dispatch resource operation request to the proper local Neutron, we need a resource routing table, which maps a resource from the central Neutron to local Neutron where it’s located.

When user issues a resource update, query or delete request, central Neutron will capture this request and extract resource id from the request, then dispatch the request to target local Neutron on the basis of the routing table.

GET

/routings

Retrieve All Resource Routings

This fetches all the resource routing entries by default, but we can apply filter(s) on the returned values to only show the specific routing entries. Accordingly the filtering condition(s) will be added to the tail of the service url separated by question mark. For example, the default service url is GET /routings, when filtering is applied, the service url becomes GET /routings?attribute=attribute_value. One or multiple conditions are supported. What’s more, project ID filter in URL query string will be ignored, and only the project ID in which the user is authorized will be used as the filter.

All items returned are sorted in descending order by ID. Because the ID is a big integer, ID with greater value means they are newly added to the resource routing table. So most recently created items will be shown first.

To reduce load on service, list operation returns a maximum number of items at a time by pagination. To navigate the collection, the parameters limit and marker can be set in the URI. For example: GET /v1.0/routings?limit=2000&marker=500. The marker parameter is the ID of the last item in the previous list. If marker is specified, we can get the results after this item. A marker with an invalid ID results in a bad request. The limit parameter sets the page size. If the client requests a limit beyond the maximum limit in configuration, then this maximum limit will be used. For each list request, if there are more items waiting to be shown besides those already in page, then a link to next page will be given. Using this link and same filtering conditions we can retrieve the following items. If the total number of items is less than the limit, then no next page link in the response. If user lists the routings without limit value specified, then maximum limit value will be used to control page size for protecting service.

Both limit and marker parameters are optional, they can be specified together or separately. Pagination and filtering can work together in routing list operations.

Normal Response Code: 200

Response

The resource routing set contains a list of resource routing entries whose attributes are described in the following table.

Name

In

Type

Description

id

body

biginteger

id is the unique identification of the resource routing.

top_id

body

string

top_id denotes the resource id on central Neutron.

bottom_id

body

string

bottom_id denotes the resource id on local Neutron.

pod_id

body

string

pod_id is the uuid of one pod(i.e., one region).

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

resource_type

body

string

resource_type denotes one of the available resource types, including network, subnet, port, router and security_group.

created_at

body

timestamp

created time of the resource routing.

updated_at

body

timestamp

updated time of the resource routing.

Response Example

This is an example of response information for GET /routings. By default, all the resource routing entries will be returned. As there is no page size limit provided by the client, so default maximum pagination limit is used. As is shown, because total number of items is less than the limit, therefore no next page link in the response.

{
    "routings": [
       {
            "updated_at": "2016-09-25 03:16:33"",
            "created_at": "2016-09-25 03:16:32",
            "top_id": "4487087e-34c7-40d8-8553-3a4206d0591b",
            "id": 3,
            "bottom_id": "834ef10b-a96f-460c-b448-b39b9f3e6b52",
            "project_id": "d937fe2ad1064a37968885a58808f7a3",
            "pod_id": "444a8ce3-9fb6-4a0f-b948-6b9d31d6b202",
            "resource_type": "security_group"
        },
        {
            "updated_at": "2016-09-25 03:16:31",
            "created_at": "2016-09-25 03:16:30",
            "top_id": "a4d786fd-0511-4fac-be45-8b9ee447324b",
            "id": 2,
            "bottom_id": "7a05748c-5d1a-485e-bd5c-e52bc39b5414",
            "project_id": "d937fe2ad1064a37968885a58808f7a3",
            "pod_id": "444a8ce3-9fb6-4a0f-b948-6b9d31d6b202",
            "resource_type": "network"
        }
    ]
}

This is an example of response information for GET /v1.0/routings?limit=2, to retrieve the first page we can only provide limit value.

{
    "routings": [
       {
           "updated_at": null,
           "created_at": "2017-06-11 12:52:46",
           "top_id": "e091d3ad-a5a9-41a1-a948-54e2a1583b8d",
           "id": 8,
           "bottom_id": "e091d3ad-a5a9-41a1-a948-54e2a1583b8d",
           "project_id": "3b2a11d52ec44d7bb8c53a18fd5105d6",
           "pod_id": "07ce2e57-fdba-4a6a-a7ce-44528108380d",
           "resource_type": "security_group"
       },
       {
           "updated_at": null,
           "created_at": "2017-06-11 12:52:46",
           "top_id": "90806f6a-2c79-4cdf-8db4-de1f3e46fe1f",
           "id": 6,
           "bottom_id": "90806f6a-2c79-4cdf-8db4-de1f3e46fe1f",
           "project_id": "3b2a11d52ec44d7bb8c53a18fd5105d6",
           "pod_id": "07ce2e57-fdba-4a6a-a7ce-44528108380d",
           "resource_type": "network"
       }
    ],
    "routings_links": [
        {
            "href": "/v1.0/routings?limit=2&marker=6",
            "rel": "next"
        }
    ]
}

This is an example of response information for GET /v1.0/routings?limit=2&marker=6, with the help of the link to next page, we can get the following items.

{
    "routings": [
       {
           "updated_at": null,
           "created_at": "2017-06-11 12:52:46",
           "top_id": "724b5ae0-d4eb-4165-a2cc-e6428719cab3",
           "id": 5,
           "bottom_id": "724b5ae0-d4eb-4165-a2cc-e6428719cab3",
           "project_id": "3b2a11d52ec44d7bb8c53a18fd5105d6",
           "pod_id": "07ce2e57-fdba-4a6a-a7ce-44528108380d",
           "resource_type": "subnet"
       },
       {
           "updated_at": null,
           "created_at": "2017-06-11 12:50:01",
           "top_id": "64b886de-62ca-4713-9461-bd77c79e2282",
           "id": 4,
           "bottom_id": null,
           "project_id": "3b2a11d52ec44d7bb8c53a18fd5105d6",
           "pod_id": "8ae8c849-ce30-43bb-8346-d4da6678fc9c",
           "resource_type": "network"
       }
    ],
    "routings_links": [
        {
            "href": "/v1.0/routings?limit=2&marker=4",
            "rel": "next"
        }
    ]
}

This is an example of response information for GET /v1.0/routings?limit=2&resource_type=port. When filter and limit are applied to the list operation, we can restrict the total number of specific routing entries.

{
    "routings": [
       {
           "updated_at": "2017-06-11 12:49:41",
           "created_at": "2017-06-11 12:49:41",
           "top_id": "interface_RegionOne_724b5ae0-d4eb-4165-a2cc-e6428719cab3",
           "id": 3,
           "bottom_id": "73845c04-a709-4b0d-a70e-71923c4c5bfc",
           "project_id": "3b2a11d52ec44d7bb8c53a18fd5105d6",
           "pod_id": "07ce2e57-fdba-4a6a-a7ce-44528108380d",
           "resource_type": "port"
       },
       {
           "updated_at": "2017-06-11 12:49:03",
           "created_at": "2017-06-11 12:49:03",
           "top_id": "dhcp_port_724b5ae0-d4eb-4165-a2cc-e6428719cab3",
           "id": 2,
           "bottom_id": "4c6f2e86-7455-4fe5-8cbc-7c3d6bc7625f",
           "project_id": "3b2a11d52ec44d7bb8c53a18fd5105d6",
           "pod_id": "6073e33e-4d4f-45dc-961a-d7d3b4a8e7f7",
           "resource_type": "port"
       }
    ],
    "routings_links": [
        {
            "href": "/v1.0/routings?limit=2&marker=2",
            "rel": "next"
        }
    ]
}

GET

/routings/{id}

Retrieve a Single Resource Routing

This fetches a single resource routing entry.

Normal Response Code: 200

Request

Name

In

Type

Description

id

path

biginteger

id is the unique identification of the resource routing.

Response

A kind of resource in central Neutron, when it is created by the Tricircle, is mapped to the same resource in local Neutron. Resource routing records this mapping relationship. All of its attributes are described in the following table.

Name

In

Type

Description

id

body

biginteger

id is the unique identification of the resource routing.

top_id

body

string

top_id denotes the resource id on central Neutron.

bottom_id

body

string

bottom_id denotes the resource id on local Neutron.

pod_id

body

string

pod_id is the uuid of one pod(i.e., one region).

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

resource_type

body

string

resource_type denotes one of the available resource types, including network, subnet, port, router and security_group.

created_at

body

timestamp

created time of the resource routing.

updated_at

body

timestamp

updated time of the resource routing.

Response Example

This is an example of response information for GET /routings/{id}.

{
    "routing": {
        "updated_at": null,
        "created_at": "2016-10-25 13:10:26",
        "top_id": "09fd7cc9-d169-4b5a-88e8-436ecf4d0bfe",
        "id": 43,
        "bottom_id": "dc80f9de-abb7-4ec6-ab7a-94f8fd1e20ef",
        "project_id": "d937fe2ad1064a37968885a58808f7a3",
        "pod_id": "444a8ce3-9fb6-4a0f-b948-6b9d31d6b202",
        "resource_type": "subnet"
    }
}

POST

/routings

Create a Resource Routing

This creates a resource routing. For a kind of resource created in central Neutron, it is mapped to the same resource in local Neutron.

Normal Response Code: 200

Request

Some essential fields of the resource routing entry are required and described in the following table.

Name

In

Type

Description

top_id

body

string

top_id denotes the resource id on central Neutron.

bottom_id

body

string

bottom_id denotes the resource id on local Neutron.

pod_id

body

string

pod_id is the uuid of one pod(i.e., one region).

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

resource_type

body

string

resource_type denotes one of the available resource types, including network, subnet, port, router and security_group.

Response

An id is assigned to the resource routing when it’s created. All routing entry’s attributes are listed below.

Name

In

Type

Description

id

body

biginteger

id is the unique identification of the resource routing.

top_id

body

string

top_id denotes the resource id on central Neutron.

bottom_id

body

string

bottom_id denotes the resource id on local Neutron.

pod_id

body

string

pod_id is the uuid of one pod(i.e., one region).

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

resource_type

body

string

resource_type denotes one of the available resource types, including network, subnet, port, router and security_group.

created_at

body

timestamp

created time of the resource routing.

updated_at

body

timestamp

updated time of the resource routing.

Request Example

This is an example of request information for POST /routings.

{
    "routing": {
        "top_id": "09fd7cc9-d169-4b5a-88e8-436ecf4d0bfg",
        "bottom_id": "dc80f9de-abb7-4ec6-ab7a-94f8fd1e20ek",
        "pod_id": "444a8ce3-9fb6-4a0f-b948-6b9d31d6b202",
        "project_id": "d937fe2ad1064a37968885a58808f7a3",
        "resource_type": "subnet"
    }
}

Response Example

This is an example of response information for POST /routings.

{
    "routing": {
        "updated_at": null,
        "created_at": "2016-11-03 03:06:38",
        "top_id": "09fd7cc9-d169-4b5a-88e8-436ecf4d0bfg",
        "id": 45,
        "bottom_id": "dc80f9de-abb7-4ec6-ab7a-94f8fd1e20ek",
        "project_id": "d937fe2ad1064a37968885a58808f7a3",
        "pod_id": "444a8ce3-9fb6-4a0f-b948-6b9d31d6b202",
        "resource_type": "subnet"
    }
}

DELETE

/routings/{id}

Delete a Resource Routing

This deletes a resource routing entry. But deleting an existing routing entry created by Tricircle itself may cause problem: Central Neutron may make wrong judgement on whether the resource exists or not without this routing entry. Moreover, related request can’t be forwarded to the proper local Neutron either.

Normal Response Code: 200

Request

Name

In

Type

Description

id

path

biginteger

id is the unique identification of the resource routing.

Response

There is no response. But we can list all the resource routing entries to verify whether the specific routing entry has been deleted or not.

PUT

/routings/{id}

Update a Resource Routing

This updates an existing resource routing entry. But updating an existing routing entry created by Tricircle itself may cause problem: Central Neutron may make wrong judgement on whether the resource exists or not without this routing entry. Moreover, related request can’t be forwarded to the proper local Neutron either.

Normal Response Code: 200

Request

Some specific attributes of the resource routing entry can be updated, but they are only limited to the fields in the following table, other fields can not be updated manually.

Name

In

Type

Description

top_id

body

string

top_id denotes the resource id on central Neutron.

bottom_id

body

string

bottom_id denotes the resource id on local Neutron.

pod_id

body

string

pod_id is the uuid of one pod(i.e., one region).

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

resource_type

body

string

resource_type denotes one of the available resource types, including network, subnet, port, router and security_group.

Response

Some specific fields of the resource routing entry will be updated. All attributes of routing entry are listed below.

Name

In

Type

Description

id

body

biginteger

id is the unique identification of the resource routing.

top_id

body

string

top_id denotes the resource id on central Neutron.

bottom_id

body

string

bottom_id denotes the resource id on local Neutron.

pod_id

body

string

pod_id is the uuid of one pod(i.e., one region).

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

resource_type

body

string

resource_type denotes one of the available resource types, including network, subnet, port, router and security_group.

created_at

body

timestamp

created time of the resource routing.

updated_at

body

timestamp

updated time of the resource routing.

Request Example

This is an example of request information for PUT /routings/{id}.

{
    "routing": {
        "resource_type": "router"
    }
}

Response Example

This is an example of response information for PUT /routings/{id}. The change of the field updated_at will be showed next time we retrieve this routing entry from the database.

{
    "routing": {
        "updated_at": null,
        "created_at": "2016-11-03 03:06:38",
        "top_id": "09fd7cc9-d169-4b5a-88e8-436ecf4d0bfg",
        "id": 45,
        "bottom_id": "dc80f9de-abb7-4ec6-ab7a-94f8fd1e20ek",
        "project_id": "d937fe2ad1064a37968885a58808f7a3",
        "pod_id": "444a8ce3-9fb6-4a0f-b948-6b9d31d6b202",
        "resource_type": "router"
    }
}

Asynchronous Job

Tricircle XJob provides OpenStack multi-region functionality. It receives jobs from the Admin API or Tricircle Central Neutron Plugin and handles them asynchronously in Local Neutron(s).

However, XJob server may strike occasionally so the tenants or administrators need to know the job status and delete or redo the failed job if necessary. Asynchronous job management APIs provide such functionality and allow user to perform CRUD operations on a job. For example, when there is a need to synchronize resource between central Neutron and local Neutron, administrator can create a job to process it.

Jobs are categorized into different groups according to their phases in lifespan. Each job lives from birth till death. Right after a job is created, its status is NEW. After picked up by the job handler its status becomes RUNNING. Then if executed successfully, its status will be SUCCESS, otherwise its status will be set to FAIL. But not all jobs go through the three phases. For job whose status is NEW, if a newer job performing the same task comes, then this newer job will be picked up by job handler, the status of the relatively old job won’t be changed until this job is cleaned from the job queue. A NEW job may also expire if it waits for too long, then its status is set to FAIL directly and skips the RUNNING phase. The expiration time span is set by administrator. All failed jobs have the opportunity to run again in next cycle of a periodical task.

After a job runs successfully it will be moved to job log table automatically, the older versions of this job like new and failed jobs are removed from job table at the same time.

There are two places to store jobs. All active jobs are stored in job table, including NEW, RUNNING, FAIL jobs and a small bunch of SUCCESS jobs that haven’t been moved to job log table timely. But job log table only contains SUCCESS jobs, they can be listed and shown like other jobs in job table, but when performing delete or redo operation on them, an exception will be raised.

GET

/jobs

Retrieve Job List

By default, this fetches all of the jobs including active jobs like NEW, FAIL and RUNNING jobs as well as SUCCESS jobs from job log. We can filter them by job type and job status to only get the specific kind of job entries, project ID filter in URL query string will be ignored, and only the project ID in which the user is authorized will be used as the filter. Accordingly the filtering condition will be added to the tail of the service url separated by question mark. For example, the default service url is GET /jobs. Using a filter the service url becomes GET /jobs?filter_name=value. One or multiple filtering conditions are supported. Particularly, job status is case insensitive when filtering the jobs, so both GET /jobs?status=NEW and GET /jobs?status=new will return the same job set.

To reduce the load on service, job list operation also supports pagination as resource routing does. It takes limit parameter as page size, and takes the item following marker parameter as starting point for next list operation.

All items in job log table are successful jobs, there are nothing new. So job table will be searched ahead of job log table. Then failed, new or running jobs will be shown first. These jobs are sorted by timestamp in descending order, if two or more jobs have the same timestamp, then they’ll be further sorted by job id in descending order.

Normal Response Code: 200

Response

In normal case, a set of expected jobs will be returned. For invalid filtering value, an empty set will be returned. For unsupported filter name, an error will be raised.

The attributes of single job are described in the following table.

Name

In

Type

Description

id

body

string

id is a uuid attribute of the job.

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

type

body

string

the type of a job.

status

body

string

job status, including NEW, RUNNING, SUCCESS, FAIL.

resource

body

object

all kinds of resources that are needed to run the job. It may also contain other necessary parameters such as pod_id and project_id that are not Neutron resources.

timestamp

body

timestamp

create or update time of the job.

Response Example

This is an example of response information for GET /jobs. By default, all the job entries will be retrieved.

{
    "jobs": [
        {
            "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
            "project_id": "d01246bc5792477d9062a76332b7514a",
            "type": "port_delete",
            "timestamp": "2017-03-03 11:05:36",
            "status": "NEW",
            "resource": {
                "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
                "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
            }
        },
        {
            "id": "b01fe514-5211-4758-bbd1-9f32141a7ac2",
            "project_id": "d01246bc5792477d9062a76332b7514a",
            "type": "seg_rule_setup",
            "timestamp": "2017-03-01 17:14:44",
            "status": "FAIL",
            "resource": {
                "project_id": "d01246bc5792477d9062a76332b7514a"
            }
        }
    ]
}

This is an example of response information for GET /v1.0/jobs?limit=2. When total number of items is equal or greater than limit value, then a link to next page will be returned.

{
    "jobs": [
        {
            "status": "SUCCESS",
            "resource": {
                "network_id": "7bf3ef1c-1f03-47b5-8191-a3d56938581b",
                "pod_id": "e6880238-3764-4de7-8644-3c09cff85b03"
            },
            "timestamp": "2017-07-26 22:36:48",
            "project_id": "cab94f5a2c6346fe956d3f45ccf84c82",
            "type": "shadow_port_setup",
            "id": "ee035edb-87a6-4dc4-ba00-06d6e62e9ad4"
        },
        {
            "status": "SUCCESS",
            "resource": {
                "router_id": "dbaa0b04-0686-45b6-8bac-a61269517c14"
            },
            "timestamp": "2017-07-26 22:36:39",
            "project_id": "cab94f5a2c6346fe956d3f45ccf84c82",
            "type": "configure_route",
            "id": "a10d9078-dee4-45d4-a352-d89d7072b766"
        }
    ],
     "jobs_links": [
        {
            "href": "/v1.0/jobs?limit=2&marker=a10d9078-dee4-45d4-a352-d89d7072b766",
            "rel": "next"
        }
    ]
}

This is an example of response information for GET /v1.0/jobs?limit=2&marker=a10d9078-dee4-45d4-a352-d89d7072b766. When marker is provided, the next list operation will start from the item following the marker.

{
    "jobs": [
        {
            "status": "SUCCESS",
            "resource": {
                "router_id": "dbaa0b04-0686-45b6-8bac-a61269517c14"
            },
            "timestamp": "2017-07-26 22:36:20",
            "project_id": "cab94f5a2c6346fe956d3f45ccf84c82",
            "type": "configure_route",
            "id": "89ae3921-2349-49fb-85ad-804b8ca99053"

        },
        {
            "status": "SUCCESS",
            "resource": {
                "network_id": "7bf3ef1c-1f03-47b5-8191-a3d56938581b",
                "pod_id": "e6880238-3764-4de7-8644-3c09cff85b03"
            },
            "timestamp": "2017-07-26 22:36:12",
            "project_id": "cab94f5a2c6346fe956d3f45ccf84c82",
            "type": "shadow_port_setup",
            "id": "afd8761b-b082-4fce-af00-afee07c3b923"
        }
    ],
     "jobs_links": [
        {
            "href": "/v1.0/jobs?limit=2&marker=afd8761b-b082-4fce-af00-afee07c3b923",
            "rel": "next"
        }
    ]
}

This is an example of response information for GET /v1.0/jobs?limit=2&marker=a10d9078-dee4-45d4-a352-d89d7072b766&type=shadow_port_setup. Pagination and filtering requirements can be met by specifying limit and filtering conditions at the same time. If there are more items waiting to be shown besides those already in page, then a link to next page will be returned. Using this link and same filtering conditions we can retrieve the following items.

{
    "jobs": [
        {
            "status": "SUCCESS",
            "resource": {
                "network_id": "7bf3ef1c-1f03-47b5-8191-a3d56938581b",
                "pod_id": "e6880238-3764-4de7-8644-3c09cff85b03"
            },
            "timestamp": "2017-07-26 22:36:12",
            "project_id": "cab94f5a2c6346fe956d3f45ccf84c82",
            "type": "shadow_port_setup",
            "id": "afd8761b-b082-4fce-af00-afee07c3b923"

        },
        {
            "status": "SUCCESS",
            "resource": {
                "network_id": "fb53ea2d-a0e8-4ed5-a2b2-f0e2fce9ff4f",
                "pod_id": "e6880238-3764-4de7-8644-3c09cff85b03"
            },
            "timestamp": "2017-07-26 22:33:45",
            "project_id": "cab94f5a2c6346fe956d3f45ccf84c82",
            "type": "shadow_port_setup",
            "id": "592ade1c-12a5-4ca3-9f75-4810c25a1604"
        }
    ],
     "jobs_links": [
        {
            "href": "/v1.0/jobs?limit=2&marker=592ade1c-12a5-4ca3-9f75-4810c25a1604",
            "rel": "next"
        }
    ]
}

GET

/jobs/detail

Retrieve Jobs with Filter(s)

Retrieve jobs from the Tricircle database. We can filter them by project ID, job type and job status. It functions the same as service GET /jobs.

Normal Response Code: 200

Response

A list of jobs will be returned. The attributes of single job are described in the following table.

Name

In

Type

Description

id

body

string

id is a uuid attribute of the job.

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

type

body

string

the type of a job.

status

body

string

job status, including NEW, RUNNING, SUCCESS, FAIL.

resource

body

object

all kinds of resources that are needed to run the job. It may also contain other necessary parameters such as pod_id and project_id that are not Neutron resources.

timestamp

body

timestamp

create or update time of the job.

Response Example

This is an example of response information for GET /jobs/detail.

{
    "jobs": [
        {
            "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
            "project_id": "d01246bc5792477d9062a76332b7514a",
            "type": "port_delete",
            "timestamp": "2017-03-03 11:05:36",
            "status": "NEW",
            "resource": {
                "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
                "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
            }
        },
        {
            "id": "b01fe514-5211-4758-bbd1-9f32141a7ac2",
            "project_id": "d01246bc5792477d9062a76332b7514a",
            "type": "seg_rule_setup",
            "timestamp": "2017-03-01 17:14:44",
            "status": "FAIL",
            "resource": {
                "project_id": "d01246bc5792477d9062a76332b7514a"
            }
        }
    ]
}

GET

/jobs/{id}

Retrieve a Single Job

This fetches a single job entry. This entry may be from job table or job log table.

Normal Response Code: 200

Request

Name

In

Type

Description

id

path

string

id is a uuid attribute of the job.

Response

The attributes of the returned job are described in the following table.

Name

In

Type

Description

id

body

string

id is a uuid attribute of the job.

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

type

body

string

the type of a job.

status

body

string

job status, including NEW, RUNNING, SUCCESS, FAIL.

resource

body

object

all kinds of resources that are needed to run the job. It may also contain other necessary parameters such as pod_id and project_id that are not Neutron resources.

timestamp

body

timestamp

create or update time of the job.

Response Example

This is an example of response information for GET /job/{id}.

{
    "job": {
        "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
        "project_id": "d01246bc5792477d9062a76332b7514a",
        "type": "port_delete",
        "timestamp": "2017-03-03 11:05:36",
        "status": "NEW",
        "resource": {
            "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
            "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
        }
    }
}

GET

/jobs/schemas

Retrieve Jobs’ Schemas

Retrieve all jobs’ schemas.

Normal Response Code: 200

Response

This returns a list of all jobs’ schemas. The architecture of job schema is described as following.

Name

In

Type

Description

type

body

string

the type of a job.

resource

body

array

all kinds of resources that are needed to run the job. It may also contain other necessary parameters such as pod_id and project_id that are not Neutron resources.

Response Example

This is an example of response information for GET /jobs/schemas.

{
    "schemas": [
        {
            "type": "configure_route",
            "resource": ["router_id"]
        },
        {
            "type": "router_setup",
            "resource": ["pod_id", "router_id", "network_id"]
        },
        {
            "type": "port_delete",
            "resource": ["pod_id", "port_id"]
        },
        {
            "type": "seg_rule_setup",
            "resource": ["project_id"]
        },
        {
            "type": "update_network",
            "resource": ["pod_id", "network_id"]
        },
        {
            "type": "subnet_update",
            "resource": ["pod_id", "subnet_id"]
        },
        {
            "type": "shadow_port_setup",
            "resource": [pod_id", "network_id"]
        }
    ]
}

POST

/job

Create a Job

This creates a new job. If target job already exists in the job table and its status is NEW, then this newer job will be picked up by job handler.

Normal Response Code: 202

Request

Some essential attributes of the job are required and they are described in the following table.

Name

In

Type

Description

type

body

string

the type of a job.

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

resource

body

object

all kinds of resources that are needed to run the job. It may also contain other necessary parameters such as pod_id and project_id that are not Neutron resources.

Response

This returns a newly created job. Its attributes are described in the following table.

Name

In

Type

Description

id

body

string

id is a uuid attribute of the job.

project_id

body

string

project_id is the uuid of a project object in KeyStone. “Tenant” is an old term for a project in Keystone. Starting in API version 3, “project” is the preferred term. They are identical in the context.

type

body

string

the type of a job.

status

body

string

job status, including NEW, RUNNING, SUCCESS, FAIL.

resource

body

object

all kinds of resources that are needed to run the job. It may also contain other necessary parameters such as pod_id and project_id that are not Neutron resources.

timestamp

body

timestamp

create time of the job.

Request Example

This is an example of request information for POST /jobs.

{
    "job": {
        "type": "port_delete",
        "project_id": "d01246bc5792477d9062a76332b7514a",
        "resource": {
            "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
            "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
        }
    }
}

Response Example

This is an example of response information for POST /jobs.

{
    "job": {
        "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
        "project_id": "d01246bc5792477d9062a76332b7514a",
        "type": "port_delete",
        "timestamp": "2017-03-03 11:05:36",
        "status": "NEW",
        "resource": {
            "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
            "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
        }
    }
}

DELETE

/jobs/{id}

Delete a Job

Delete a failed or duplicated job from the job table. If a user tries to delete a job from job log table, an error will be raised.

Normal Response Code: 200

Request

Name

In

Type

Description

id

path

string

id is a uuid attribute of the job.

Response

A pair of curly braces will be returned if succeeds, otherwise an exception will be thrown. We can list jobs to verify whether it has been deleted successfully or not.

PUT

/jobs/{id}

Redo a Job

Redo a halted job brought by the XJob server corruption or network failures. The job handler will redo a failed job with time interval, but this Admin API will redo a job immediately. If a user tries to redo a job in job log table, an error will be raised.

Normal Response Code: 200

Request

Only job id is needed. We use PUT method to redo a job. Regularly PUT method requires a request body, but considering the job redo operation doesn’t need more information other than job id, we will issue this request without request body.

Name

In

Type

Description

id

path

string

id is a uuid attribute of the job.

Response

Nothing will be returned for this request, but we can monitor its status through the execution state.