Add devices endpoint
There is a need to be able to query devices in general instead of specific types of device, to allow more useful collections to be returned such as related devices. blueprint list-devices APIImpact Change-Id: I8a871eb8b10bae331869130b9c81173ed3528a66
This commit is contained in:
git-harry
parent
e37a88636e
commit
32a3d7e751
|
|
@ -0,0 +1,373 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
===============
|
||||
Listing Devices
|
||||
===============
|
||||
|
||||
https://blueprints.launchpad.net/craton/+spec/list-devices
|
||||
|
||||
Craton has separate endpoints for different types of device. Devices of
|
||||
different types can be linked in a parent-child relationship. Craton does not
|
||||
offer a mechanism to easily display devices of different types making queries
|
||||
tracking relationships cumbersome.
|
||||
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
As a operator I want to be able to list a device's descendants so that I can
|
||||
visualise or operate on a collection of related devices.
|
||||
|
||||
Currently Craton supports two types of devices - hosts and network-devices.
|
||||
Devices include the optional attribute parent_id to create a parent-child
|
||||
relationship between two devices. So if one has two network-devices and one is
|
||||
the parent of the other, the network-devices endpoint can be queried to find
|
||||
the child device using the ID of the parent, e.g.
|
||||
|
||||
GET /v1/network-devices?parent_id=1
|
||||
|
||||
If a third device is added, this time as a child device of the second device,
|
||||
it is not possible to directly identify it from the root device. A second
|
||||
query would need to be made using the ID of the second device, e.g.
|
||||
|
||||
GET /v1/network-devices?parent_id=2
|
||||
|
||||
This means to represent a complete tree could potentially require a large
|
||||
number of queries or the client would need to get all the devices and then link
|
||||
them up itself.
|
||||
|
||||
In addition, given that both a host and a network-device can have the same
|
||||
parent, currently both endpoints need to be queried for any parent_id to get
|
||||
all the devices.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
To meet the needs of the user story and resolve the problems outlined above,
|
||||
this spec proposes the introduction of a new endpoint for devices to allow for
|
||||
the querying of devices as a whole.
|
||||
|
||||
The endpoint will be /v1/devices and will support:
|
||||
|
||||
- querying against a set of attributes common to all devices
|
||||
- optionally including the descendants of any query
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
- the traversal of the tree could be left to the client, this would likely be a
|
||||
slow process for large deployments
|
||||
- the existing endpoints, i.e. /v1/hosts and /v1/network-devices, could be
|
||||
allowed to return other types of device however this is likely to be
|
||||
confusing and lead to mistakes uses the output.
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
|
||||
Endpoint: /v1/devices
|
||||
Method: GET
|
||||
Description: List project devices
|
||||
Normal response code: 200
|
||||
Expected error response codes: 400
|
||||
|
||||
Parameters schema: {
|
||||
"type": "object",
|
||||
"additionalProperties": False,
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "integer",
|
||||
},
|
||||
"region_id": {
|
||||
"type": "integer",
|
||||
},
|
||||
"cell_id": {
|
||||
"type": "integer",
|
||||
},
|
||||
"parent_id": {
|
||||
"type": "integer",
|
||||
},
|
||||
"active": {
|
||||
"type": "boolean",
|
||||
},
|
||||
"descendants": {
|
||||
"default": False,
|
||||
"type": "boolean",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
Response schema: {
|
||||
"type": "object",
|
||||
"additionalProperties": False,
|
||||
"properties": {
|
||||
"devices": {
|
||||
"type": "object",
|
||||
"additionalProperties": False,
|
||||
"properties": {
|
||||
"hosts": {
|
||||
"type": "array",
|
||||
"items": DefinitionsHost,
|
||||
},
|
||||
"network-devices": {
|
||||
"type": "array",
|
||||
"items": DefinitionNetworkDeviceResponse,
|
||||
},
|
||||
},
|
||||
},
|
||||
"links": DefinitionsPaginationLinks,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
Example:
|
||||
Request
|
||||
http://example.com/v1/devices
|
||||
Response
|
||||
{
|
||||
"devices": {
|
||||
"hosts": [
|
||||
{
|
||||
"active": true,
|
||||
"cell_id": 4,
|
||||
"created_at": "2017-02-16T14:28:55.000000",
|
||||
"device_type": "server",
|
||||
"id": 20,
|
||||
"ip_address": "192.168.1.20",
|
||||
"links": [
|
||||
{
|
||||
"href": "http://example.com/v1/cells/4",
|
||||
"rel": "up"
|
||||
}
|
||||
],
|
||||
"name": "host1.DFW.C0002.C-2.example2.com",
|
||||
"note": null,
|
||||
"parent_id": null,
|
||||
"project_id": "b9f10eca-66ac-4c27-9c13-9d01e65f96b4",
|
||||
"region_id": 2,
|
||||
"updated_at": null
|
||||
}
|
||||
... more hosts ...,
|
||||
],
|
||||
"network-devices": [
|
||||
{
|
||||
"access_secret_id": null,
|
||||
"active": true,
|
||||
"cell_id": 4,
|
||||
"created_at": "2017-02-16T14:28:55.000000",
|
||||
"device_type": "switch",
|
||||
"id": 16,
|
||||
"ip_address": "10.10.1.1",
|
||||
"links": [
|
||||
{
|
||||
"href": "http://example.com/v1/cells/4",
|
||||
"rel": "up"
|
||||
}
|
||||
],
|
||||
"model_name": "model-x",
|
||||
"name": "switch1.C0002.DFW.example.com",
|
||||
"os_version": "version-1",
|
||||
"parent_id": null,
|
||||
"project_id": "b9f10eca-66ac-4c27-9c13-9d01e65f96b4",
|
||||
"region_id": 2,
|
||||
"updated_at": null,
|
||||
"vlans": null
|
||||
},
|
||||
... more network-devices ...,
|
||||
],
|
||||
},
|
||||
"links": [
|
||||
{
|
||||
"href": "http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid",
|
||||
"rel": "first"
|
||||
},
|
||||
{
|
||||
"href": "http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid",
|
||||
"rel": "prev"
|
||||
},
|
||||
{
|
||||
"href": "http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid",
|
||||
"rel": "self"
|
||||
},
|
||||
{
|
||||
"href": "http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid&marker=20",
|
||||
"rel": "next"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Example:
|
||||
Request
|
||||
http://example.com/v1/devices?parent_id=16&descendants=true
|
||||
Response
|
||||
{
|
||||
"devices": {
|
||||
"network-devices": [
|
||||
{
|
||||
"access_secret_id": null,
|
||||
"active": true,
|
||||
"cell_id": 4,
|
||||
"created_at": "2017-02-16T14:28:55.000000",
|
||||
"device_type": "switch",
|
||||
"id": 17,
|
||||
"ip_address": "10.10.1.2",
|
||||
"links": [
|
||||
{
|
||||
"href": "http://example.com/v1/network-devices/16",
|
||||
"rel": "up"
|
||||
}
|
||||
],
|
||||
"model_name": "model-x",
|
||||
"name": "switch2.C0002.DFW.example.com",
|
||||
"os_version": "version-1",
|
||||
"parent_id": 16,
|
||||
"project_id": "b9f10eca-66ac-4c27-9c13-9d01e65f96b4",
|
||||
"region_id": 2,
|
||||
"updated_at": null,
|
||||
"vlans": null
|
||||
},
|
||||
{
|
||||
"access_secret_id": null,
|
||||
"active": true,
|
||||
"cell_id": 4,
|
||||
"created_at": "2017-02-16T14:28:55.000000",
|
||||
"device_type": "switch",
|
||||
"id": 18,
|
||||
"ip_address": "10.10.1.3",
|
||||
"links": [
|
||||
{
|
||||
"href": "http://example.com/v1/network-devices/17",
|
||||
"rel": "up"
|
||||
}
|
||||
],
|
||||
"model_name": "model-x",
|
||||
"name": "switch3.C0002.DFW.example.com",
|
||||
"os_version": "version-1",
|
||||
"parent_id": 17,
|
||||
"project_id": "b9f10eca-66ac-4c27-9c13-9d01e65f96b4",
|
||||
"region_id": 2,
|
||||
"updated_at": null,
|
||||
"vlans": null
|
||||
},
|
||||
],
|
||||
"hosts": [
|
||||
{
|
||||
"active": true,
|
||||
"cell_id": 4,
|
||||
"created_at": "2017-02-16T14:28:55.000000",
|
||||
"device_type": "server",
|
||||
"id": 200,
|
||||
"ip_address": "192.168.1.20",
|
||||
"links": [
|
||||
{
|
||||
"href": "http://example.com/v1/network-devices/16",
|
||||
"rel": "up"
|
||||
}
|
||||
],
|
||||
"name": "host10.DFW.C0002.C-2.example2.com",
|
||||
"note": null,
|
||||
"parent_id": 16,
|
||||
"project_id": "b9f10eca-66ac-4c27-9c13-9d01e65f96b4",
|
||||
"region_id": 2,
|
||||
"updated_at": null
|
||||
},
|
||||
],
|
||||
},
|
||||
"links": [
|
||||
{
|
||||
"href": "http://example.com/v1/devices?parent_id=16&descendants=true&sort_dir=asc&limit=30&sort_keys=created_at%2Cid",
|
||||
"rel": "first"
|
||||
},
|
||||
{
|
||||
"href": "http://example.com/v1/devices?parent_id=16&descendants=true&sort_dir=asc&limit=30&sort_keys=created_at%2Cid",
|
||||
"rel": "prev"
|
||||
},
|
||||
{
|
||||
"href": "http://example.com/v1/devices?parent_id=16&descendants=true&sort_dir=asc&limit=30&sort_keys=created_at%2Cid",
|
||||
"rel": "self"
|
||||
},
|
||||
{
|
||||
"href": "http://example.com/v1/devices?parent_id=16&descendants=true&sort_dir=asc&limit=30&sort_keys=created_at%2Cid&marker=20",
|
||||
"rel": "next"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
None
|
||||
|
||||
Notifications impact
|
||||
--------------------
|
||||
|
||||
None
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
- /v1/devices with need to be supported by the client.
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
Given the nature of this new endpoint, there is a strong likelihood that it
|
||||
will be used for most requests where listing devices is required, even if the
|
||||
user is only after one type.
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
None
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
None
|
||||
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
- git-harry
|
||||
|
||||
Other contributors:
|
||||
- None
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
- add /v1/devices endpoint
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
A full set of functional and unit tests will need to be added.
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
The repo documentation will require updating but this is handled by the
|
||||
project.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
None
|
||||
Loading…
Reference in New Issue