|
|
| Line 1: |
Line 1: |
| − | == General API information ==
| + | This page has migrated to [http://blazar.readthedocs.io/en/latest/restapi/index.html here] |
| − | | |
| − | This page contains base information about the Climate REST API design, including operations with different Climate resource types and examples of possible requests and responses. Climate supports JSON data serialization format, which means that requests with non empty body have to contain "application/json" Content-Type header or it should be added ".json" extension to the resource name in the request. | |
| − | | |
| − | This should look like the following:
| |
| − | | |
| − | GET /v1/{tenant_id}/leases.json
| |
| − | | |
| − | or
| |
| − | | |
| − | GET /v1/{tenant_id}/leases
| |
| − | Accept: application/json
| |
| − | | |
| − | == Leases ==
| |
| − | | |
| − | Lease is the main abstraction for the user in the Climate case. Lease means some kind of contract where start time, end time and resources to be reserved are mentioned.
| |
| − | | |
| − | ==== Lease ops ====
| |
| − | | |
| − | {| class="wikitable"
| |
| − | |-
| |
| − | ! Verb !! URI !! Description
| |
| − | |-
| |
| − | |
| |
| − | GET
| |
| − | ||
| |
| − | /v1/leases
| |
| − | || Lists all leases registered in Climate for tenant defined in headers.
| |
| − | |-
| |
| − | |
| |
| − | POST
| |
| − | ||
| |
| − | /v1/leases
| |
| − | || Create new lease with passed parameters.
| |
| − | |-
| |
| − | |
| |
| − | GET
| |
| − | ||
| |
| − | /v1/leases/{lease_id}
| |
| − | || Shows information about specified lease.
| |
| − | |-
| |
| − | |
| |
| − | PUT
| |
| − | ||
| |
| − | /v1/leases/{lease_id}
| |
| − | || Updates specified lease (only name modification and prolonging are possible).
| |
| − | |-
| |
| − | |
| |
| − | DELETE
| |
| − | ||
| |
| − | /v1/leases/{lease_id}
| |
| − | || Deletes specified lease and frees all reserved resources.
| |
| − | |}
| |
| − | | |
| − | ==== List all leases ====
| |
| − | | |
| − | /v1/leases
| |
| − | | |
| − | * Normal Response Code: 200 (OK)
| |
| − | * Returns the list of all leases.
| |
| − | * Does not require a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | GET http://climate_node:1234/v1/leases
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 200 OK''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'end_date': '2345',
| |
| − | 'events': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'event_type': 'start_lease',
| |
| − | 'id': 'event_id_1',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '1234',
| |
| − | 'updated_at': None
| |
| − | },
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:25:52',
| |
| − | 'event_type': 'end_lease',
| |
| − | 'id': 'event_id_2',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '2345',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'name': 'lease_foo',
| |
| − | 'reservations': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'id': 'reservation_id',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'resource_id': '1234-1234-1234',
| |
| − | 'resource_type': 'virtual:instance',
| |
| − | 'status': 'pending',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'start_date': '1234',
| |
| − | 'tenant_id': 'tenant_id',
| |
| − | 'trust_id': 'trust_id',
| |
| − | 'updated_at': None,
| |
| − | 'user_id': 'user_id'
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | ==== Create new lease ====
| |
| − | | |
| − | /v1/leases
| |
| − | | |
| − | * Normal Response Code: 202 (ACCEPTED)
| |
| − | * Returns the information about created lease.
| |
| − | * Requires a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | POST http://climate_node:1234/v1/leases
| |
| − |
| |
| − | {
| |
| − | "name": "lease_foo",
| |
| − | "start_date": "1234",
| |
| − | "end_date": "2345",
| |
| − | "reservations": [
| |
| − | {
| |
| − | "resource_id": "1234-1234-1234",
| |
| − | "resource_type": "virtual:instance"
| |
| − | }
| |
| − | ],
| |
| − | "events": []
| |
| − | }
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 202 ACCEPTED''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'end_date': '2345',
| |
| − | 'events': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'event_type': 'start_lease',
| |
| − | 'id': 'event_id_1',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '1234',
| |
| − | 'updated_at': None
| |
| − | },
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:25:52',
| |
| − | 'event_type': 'end_lease',
| |
| − | 'id': 'event_id_2',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '2345',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'name': 'lease_foo',
| |
| − | 'reservations': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'id': 'reservation_id',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'resource_id': '1234-1234-1234',
| |
| − | 'resource_type': 'virtual:instance',
| |
| − | 'status': 'pending',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'start_date': '1234',
| |
| − | 'tenant_id': 'tenant_id',
| |
| − | 'trust_id': 'trust_id',
| |
| − | 'updated_at': None,
| |
| − | 'user_id': 'user_id'
| |
| − | }
| |
| − | | |
| − | ==== Show info about lease ====
| |
| − | | |
| − | /v1/leases/{lease_id}
| |
| − | | |
| − | * Normal Response Code: 200 (OK)
| |
| − | * Returns the information about specified lease.
| |
| − | * Does not require a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | GET http://climate_node:1234/v1/leases/aaaa-bbbb-cccc-dddd
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 200 OK''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'end_date': '2345',
| |
| − | 'events': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'event_type': 'start_lease',
| |
| − | 'id': 'event_id_1',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '1234',
| |
| − | 'updated_at': None
| |
| − | },
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:25:52',
| |
| − | 'event_type': 'end_lease',
| |
| − | 'id': 'event_id_2',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '2345',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'name': 'lease_foo',
| |
| − | 'reservations': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'id': 'reservation_id',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'resource_id': '1234-1234-1234',
| |
| − | 'resource_type': 'virtual:instance',
| |
| − | 'status': 'pending',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'start_date': '1234',
| |
| − | 'tenant_id': 'tenant_id',
| |
| − | 'trust_id': 'trust_id',
| |
| − | 'updated_at': None,
| |
| − | 'user_id': 'user_id'
| |
| − | }
| |
| − | | |
| − | ==== Update existing lease ====
| |
| − | | |
| − | /v1/leases/{lease_id}
| |
| − | | |
| − | * Normal Response Code: 202 ACCEPTED
| |
| − | * Returns the updated information about lease.
| |
| − | * Requires a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | PUT http://climate_node:1234/v1/leases/aaaa-bbbb-cccc-dddd
| |
| − |
| |
| − | {
| |
| − | "name": "new_name",
| |
| − | "end_date": "new_date",
| |
| − | }
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 202 ACCEPTED''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'end_date': 'new_date',
| |
| − | 'events': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'event_type': 'start_lease',
| |
| − | 'id': 'event_id_1',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '1234',
| |
| − | 'updated_at': None
| |
| − | },
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:25:52',
| |
| − | 'event_type': 'end_lease',
| |
| − | 'id': 'event_id_2',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'status': 'UNDONE',
| |
| − | 'time': '2345',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'name': 'new_name',
| |
| − | 'reservations': [
| |
| − | {
| |
| − | 'created_at': '2014-02-26 10:00:00',
| |
| − | 'id': 'reservation_id',
| |
| − | 'lease_id': 'aaaa-bbbb-cccc-dddd',
| |
| − | 'resource_id': '1234-1234-1234',
| |
| − | 'resource_type': 'virtual:instance',
| |
| − | 'status': 'pending',
| |
| − | 'updated_at': None
| |
| − | }
| |
| − | ],
| |
| − | 'start_date': '1234',
| |
| − | 'tenant_id': 'tenant_id',
| |
| − | 'trust_id': 'trust_id',
| |
| − | 'updated_at': None,
| |
| − | 'user_id': 'user_id'
| |
| − | }
| |
| − | | |
| − | ==== Delete existing lease ====
| |
| − | | |
| − | /v1/leases/{lease_id}
| |
| − | | |
| − | * Normal Response Code: 204 NO CONTENT
| |
| − | * Does not require a request body.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | DELETE http://climate_node:1234/v1/leases/aaaa-bbbb-cccc-dddd
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 204 NO CONTENT''
| |
| − | ''Content-Type: application/json''
| |
| − | | |
| − | == Hosts ==
| |
| − | | |
| − | Host is the main abstraction for a Nova Compute host. It is necessary to enroll compute hosts in Climate so that the host becomes dedicated to Climate, and won't accept other VM creation requests but the ones asked subsequently by leases requests for dedicated hosts within Climate.
| |
| − | If no extra arguments but the name are passed when creating a host, Climate will take Nova specifications, like VCPUs, RAM or cpu_info. There is a possibility to add what we call arbitrary extra parameters (not provided within the Nova model) like number of GPUs, color of the server or anything that needs to be filtered for a user query.
| |
| − | | |
| − | ==== Hosts ops ====
| |
| − | | |
| − | {| class="wikitable"
| |
| − | |-
| |
| − | ! Verb !! URI !! Description
| |
| − | |-
| |
| − | |
| |
| − | GET
| |
| − | ||
| |
| − | /v1/os-hosts
| |
| − | || Lists all hosts registered in Climate.
| |
| − | |-
| |
| − | |
| |
| − | POST
| |
| − | ||
| |
| − | /v1/os-hosts
| |
| − | || Create new host with possibly extra parameters.
| |
| − | |-
| |
| − | |
| |
| − | GET
| |
| − | ||
| |
| − | /v1/os-hosts/{host_id}
| |
| − | || Shows information about specified host, including extra parameters if existing.
| |
| − | |-
| |
| − | |
| |
| − | PUT
| |
| − | ||
| |
| − | /v1/os-hosts/{host_id}
| |
| − | || Updates specified host (only extra parameters are possible to change).
| |
| − | |-
| |
| − | |
| |
| − | DELETE
| |
| − | ||
| |
| − | /v1/os-hosts/{host_id}
| |
| − | || Deletes specified host.
| |
| − | |}
| |
| − | | |
| − | ==== List all hosts ====
| |
| − | | |
| − | /v1/hosts
| |
| − | | |
| − | * Normal Response Code: 200 (OK)
| |
| − | * Returns the list of all hosts.
| |
| − | * Does not require a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | GET http://climate_node:1234/v1/os-hosts
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 200 OK''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | [
| |
| − | {
| |
| − | 'cpu_info': '{...}',
| |
| − | 'created_at': '2014-01-01 08:00:00',
| |
| − | 'hypervisor_hostname': 'compute1',
| |
| − | 'hypervisor_type': 'QEM',
| |
| − | 'hypervisor_version': 1000000,
| |
| − | 'id': '1',
| |
| − | 'local_gb': 8,
| |
| − | 'memory_mb': 3954,
| |
| − | 'status': None,
| |
| − | 'updated_at': None,
| |
| − | 'vcpus': 2
| |
| − | },
| |
| − | {
| |
| − | 'cpu_info': '{...}',
| |
| − | 'created_at': '2014-01-01 09:00:00',
| |
| − | 'hypervisor_hostname': 'compute2',
| |
| − | 'hypervisor_type': 'QEM',
| |
| − | 'hypervisor_version': 1000000,
| |
| − | 'id': '2',
| |
| − | 'local_gb': 8,
| |
| − | 'memory_mb': 3954,
| |
| − | 'status': None,
| |
| − | 'updated_at': None,
| |
| − | 'vcpus': 2
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | ==== Create new host ====
| |
| − | | |
| − | /v1/os-hosts
| |
| − | | |
| − | * Normal Response Code: 202 (ACCEPTED)
| |
| − | * Returns the information about created host, including extra parameters if any.
| |
| − | * Requires a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | POST http://climate_node:1234/v1/os-hosts
| |
| − | | |
| − | {
| |
| − | "name": "compute",
| |
| − | "values": {
| |
| − | "banana": "true"
| |
| − | }
| |
| − | }
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 202 ACCEPTED''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | {
| |
| − | 'banana': 'true',
| |
| − | 'cpu_info': '{"vendor": "Intel", "model": "pentium",
| |
| − | "arch": "x86_64", "features": [
| |
| − | "lahf_lm", "lm", "nx", "syscall", "hypervisor",
| |
| − | "aes", "popcnt", "x2apic", "sse4.2", "cx16",
| |
| − | "ssse3", "pni", "ss", "sse2", "sse", "fxsr",
| |
| − | "clflush", "pse36", "pat", "cmov", "mca",
| |
| − | "pge", "mtrr", "apic", "pae"],
| |
| − | "topology": {
| |
| − | "cores": 1, "threads": 1, "sockets": 2}}',
| |
| − | 'created_at': '2014-02-26 08:00:00',
| |
| − | 'hypervisor_hostname': 'compute',
| |
| − | 'hypervisor_type': 'QEM',
| |
| − | 'hypervisor_version': 1000000,
| |
| − | 'id': '1',
| |
| − | 'local_gb': 8,
| |
| − | 'memory_mb': 3954,
| |
| − | 'status': None,
| |
| − | 'updated_at': None,
| |
| − | 'vcpus': 2
| |
| − | }
| |
| − | | |
| − | ==== Show info about host ====
| |
| − | | |
| − | /v1/os-hosts/{host_id}
| |
| − | | |
| − | * Normal Response Code: 200 (OK)
| |
| − | * Returns the information about specified host, including extra parameters if any.
| |
| − | * Does not require a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | GET http://climate_node:1234/v1/os-hosts/1
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 200 OK''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | {
| |
| − | 'banana': 'true',
| |
| − | 'cpu_info': '{"vendor": "Intel", "model": "pentium",
| |
| − | "arch": "x86_64", "features": [
| |
| − | "lahf_lm", "lm", "nx", "syscall", "hypervisor",
| |
| − | "aes", "popcnt", "x2apic", "sse4.2", "cx16",
| |
| − | "ssse3", "pni", "ss", "sse2", "sse", "fxsr",
| |
| − | "clflush", "pse36", "pat", "cmov", "mca",
| |
| − | "pge", "mtrr", "apic", "pae"],
| |
| − | "topology": {
| |
| − | "cores": 1, "threads": 1, "sockets": 2}}',
| |
| − | 'created_at': '2014-02-26 08:00:00',
| |
| − | 'hypervisor_hostname': 'compute',
| |
| − | 'hypervisor_type': 'QEM',
| |
| − | 'hypervisor_version': 1000000,
| |
| − | 'id': '1',
| |
| − | 'local_gb': 8,
| |
| − | 'memory_mb': 3954,
| |
| − | 'status': None,
| |
| − | 'updated_at': None,
| |
| − | 'vcpus': 2
| |
| − | }
| |
| − | | |
| − | ==== Update existing host ====
| |
| − | | |
| − | /v1/os-hosts/{host_id}
| |
| − | | |
| − | * Normal Response Code: 202 ACCEPTED
| |
| − | * Returns the updated information about host.
| |
| − | * Requires a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | PUT http://climate_node:1234/v1/os-hosts/1
| |
| − |
| |
| − | {
| |
| − | "values": {
| |
| − | "banana": "false"
| |
| − | }
| |
| − | }
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 202 ACCEPTED''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | {
| |
| − | 'banana': 'false',
| |
| − | 'cpu_info': '{"vendor": "Intel", "model": "pentium",
| |
| − | "arch": "x86_64", "features": [
| |
| − | "lahf_lm", "lm", "nx", "syscall", "hypervisor",
| |
| − | "aes", "popcnt", "x2apic", "sse4.2", "cx16",
| |
| − | "ssse3", "pni", "ss", "sse2", "sse", "fxsr",
| |
| − | "clflush", "pse36", "pat", "cmov", "mca",
| |
| − | "pge", "mtrr", "apic", "pae"],
| |
| − | "topology": {
| |
| − | "cores": 1, "threads": 1, "sockets": 2}}',
| |
| − | 'created_at': '2014-02-26 08:00:00',
| |
| − | 'hypervisor_hostname': 'compute',
| |
| − | 'hypervisor_type': 'QEM',
| |
| − | 'hypervisor_version': 1000000,
| |
| − | 'id': '1',
| |
| − | 'local_gb': 8,
| |
| − | 'memory_mb': 3954,
| |
| − | 'status': None,
| |
| − | 'updated_at': None,
| |
| − | 'vcpus': 2
| |
| − | }
| |
| − | | |
| − | ==== Delete existing host ====
| |
| − | | |
| − | /v1/os-hosts/{host_id}
| |
| − | | |
| − | * Normal Response Code: 204 NO CONTENT
| |
| − | * Does not require a request body.
| |
| − | | |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | DELETE http://climate_node:1234/v1/os-hosts/1
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 204 ACCEPTED''
| |
| − | ''Content-Type: application/json''
| |
| − | | |
| − | == Plugins ==
| |
| − | | |
| − | Plugins are working with different resources types. Technically speaking they are implemented using stevedore extensions. Currently plugins API requests are not implemented, listed below examples are their possible view.
| |
| − | | |
| − | ==== Plugins ops ====
| |
| − | | |
| − | {| class="wikitable"
| |
| − | |-
| |
| − | ! Verb !! URI !! Description
| |
| − | |-
| |
| − | |
| |
| − | GET
| |
| − | ||
| |
| − | /v1/plugins
| |
| − | || Lists all plugins used now in Climate.
| |
| − | |}
| |
| − | | |
| − | ==== List plugins ====
| |
| − | | |
| − | /v1/plugins
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Request:''
| |
| − | | |
| − | GET http://climate_node:1234/v1/plugins
| |
| − | | |
| − | ''Response:''
| |
| − | | |
| − | ''HTTP/1.1 200 OK''
| |
| − | ''Content-Type: application/json''
| |
| − |
| |
| − | {
| |
| − | "plugins": [
| |
| − | {
| |
| − | "name": "basic_vm_plugin",
| |
| − | "resource_type": "virtual:instance",
| |
| − | "description": "Works with Nova instances. Unshelves VM when lease begins, supports VM snapshoting, suspending and deletion when lease ends."
| |
| − | },
| |
| − | {
| |
| − | "name": "physical_host_plugin",
| |
| − | "resource_type": "physical:host",
| |
| − | "description": "Works with compute hosts. Creates aggregate with reserved hosts on lease start and returns them back to free pool on lease end."
| |
| − | }
| |
| − | ]
| |
| − | }
| |
