openstack/ironic
Code Issues Proposed changes
ironic/doc/source/dev/api-spec-v1.rst
Devananda van der Veen 676a157f42 More doc updates. 
Create doc/source/dev/ directory, and add several files that got
accidentaly ignored because they were under doc/source/api/.

Also move some files from doc/source into doc/source/dev to clean up the
base doc dir.

Change-Id: Ief9777216db82ec3be32b7a73e2d268a3a973ef8
2013-05-29 16:20:58 -07:00

1022 lines
28 KiB
ReStructuredText
Raw Blame History

=========================
Ironic REST API v1.0 Spec
=========================
Contents
#########
- `General Concepts`_
- `Resource Definitions`_
- `Areas To Be Defined`_
General Concepts
#################
- `Links and Relationships`_
- Queries_
- `State Transitions`_
- `Vendor MIME Types`_
- Pagination_
- SubResource_
- Security_
- Versioning_
Links and Relationships
------------------------
Relationships between top level resources are represented as links. Links take
the form similar to that of the AtomPub standard and include a 'rel' and 'href'
element. For one to many relations between resources, a link will be provided
that points to a collection of resources that satisfies the many side of the
relationship.
All collections, top level resources and sub resources have links that provide
a URL to itself and a bookmarked version of itself. These links are defined
via "rel": "self" and "rel": "bookmark".
Queries
-------
Queries are allowed on collections that allow some filtering of the resources
returned in the collection document.
A simple example::
/nodes/?arch=x86_64
State Transitions
------------------
Some resources have states. A node is a typical example. It may have various
possible states, such as ON, OFF, DEPLOYED, REBOOTING and so on. States are
governed internally via a finite state machine.
You can change the state of a resource by updating its state SubResource_ and
setting the "current" field to one of the states codes shown in
"available_states" field.
This is often achieved in other APIs using HTTP query paramter, such as
"node/1/?actions=reboot". This is adding behaviour to the underlying protocol
which should not be done in a REST API.
See: https://code.google.com/p/implementing-rest/wiki/RESTAPIRules
Vendor MIME Types
------------------
The initial vendor MIME types will represent format and version. i.e. v1 and
json. Future MIME types can be used to get better performance from the API.
For example, we could define a new MIME type vnd.openstack.ironic.min,v1 that
could be minimize document size or vnd.openstack.ironic.max,v1 that could be
used to return larger documents but minimize the number of HTTP requests need
to perform some action.
Pagination
-----------
HTTP Queries can be used to paginate collection response documents.
Example::
/nodes/?limit=200&marker=105
Link headers are used to return "next" and "previous" links for paginated
collections. The links will follow the same linking pattern used throughout
the API based on the AtomPub protocol:
link rel="next" "href"="http://localhost:8080/nodes?limit=200&marker=201"
SubResource
------------
Sub Resources are resources that only exist within another top level resource.
Sub resources are not neccessarily useful on their own, but are defined so that
smaller parts of resource descriptions can be viewed and edited independently
of the resource itself.
For example, if a client wanted to change the deployment configuration for a
specific node, the client could update the deployment part of the node's
ManagementConfiguration_ with the new parameters directly at:
/nodes/1/management_configuration/deploy
Security
---------
To be Defined
Versioning
-----------
The API uses 2 ways of specifying versions through the use of either a vendor
MIME type, specified in the version resource and also through a URL that
contains the version ID. The API has a default version as specified in the
API resource. Failure to specify a version specific MIME type or a URL encoded
with a particular version will result the API will assume the use of the
default version. When both URL version and MIME type are specified and
conflicting the URL version takes precedence.
Resource Definitions
#####################
Top Level Resources
--------------------
- API_
- Version_
- Node_
- Chassis_
- Port_
- Driver_
- Image_
Sub Resources
---------------
- ManagementConfiguration_
- MetaData_
- State_
API
----
An API resource is returned at the root URL (or entry point) to the API. From
here all versions and subsequent resources are discoverable.
Usage
^^^^^^
======= ============= =====================
Verb Path Response
======= ============= =====================
GET / Get the API resource
======= ============= =====================
Fields
^^^^^^^
type
The type of this resource, i.e. api
name
The name of the API, e,g, openstack.ironic.api
description
Some information about this API
versions
A link to all the versions available in this API
default_version
A link to the default version used when no version is specified in the URL
or in the content-type
Example
^^^^^^^^
JSON structure of an API::
{
"type": "api",
"name": "openstack ironic API",
"description": "foobar",
"versions": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/api/versions/"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/api/versions"
}
]
},
"default_version": {
"id": "1.0",
"type": "version",
"links": [{
"rel": "self",
"href": "http://localhost:8080/api/versions/1.0/"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/api/versions/1.0/"
}
]
}
}
Version
--------
A version is essentially an API version and contains information on how to use
this version as well as links to documentation, schemas and the available
content-types that are supported.
Usage
^^^^^^
======= =============== =====================
Verb Path Response
======= =============== =====================
GET /versions Returns a list of versions
GET /versions/<id> Receive a specific version
======= =============== =====================
Fields
^^^^^^^
id
The ID of the version, also acts as the release number
type
The type of this resource, i.e. version
media_types
An array of supported media types for this version
description
Some information about this API
links
Contains links that point to a specific URL for this version (as an
alternate to using MIME types) as well as links to documentation and
schemas
The version also contains links to all of the top level resources available in
this version of the API. Example below shows chassis, ports, drivers and
nodes. Different versions may have more or less resources.
Example
^^^^^^^^
JSON structure of a Version::
{
"id": "1",
"type": "version",
"media_types": [{
"base": "application/json",
"type": "application/vnd.openstack.ironic.v1+json"
}
],
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1/"
}, {
"rel": "describedby",
"type": "application/pdf",
"href": "http://docs.openstack.ironic.com/api/v1.pdf"
}, {
"rel": "describedby",
"type": "application/vnd.sun.wadl+xml",
"href": "http://docs.openstack.ironic.com/api/v1/application.wadl"
}
],
"chassis": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/chassis"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/chassis"
}
]
},
"ports": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/ports"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/ports"
}
]
},
"drivers": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/drivers"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers"
}
]
}
"nodess": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/nodes"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes"
}
]
}
}
Node
-----
Usage
^^^^^^
======= ============= ==========
Verb Path Response
======= ============= ==========
GET /nodes List nodes.
GET /nodes/<id> Retrieve a specific node.
POST /nodes Create a new node
PUT /nodes/<id> Update a node
DELETE /nodes/<id> Delete node and all associated ports
======= ============= ==========
Fields
^^^^^^^
id
Unique ID for this node
type
The type of this resource, i.e. node
arch
The node CPU architecture
cpus
The number of available CPUs
disk
The amount of available storage space in GB
ram
The amount of available RAM in MB
meta_data
This node's meta data see: MetaData_
image
A reference to this node's current image see: Image_
state
This node's state, see State_
chassis
The chassis this node belongs to see: Chassis_
ports
A list of available ports for this node see: Port_
management_configuration
This node's management configuration see: ManagementConfiguration_
Example
^^^^^^^^
JSON structure of a node::
{
"id": "fake-node-id",
"type": "node",
"arch": "x86_64",
"cpus": 8,
"disk": 1024,
"ram": 4096,
"meta_data": {
"data_centre": "us.east.1",
"function": "high_speed_cpu",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/nodes/1/meta-data"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/meta-data"
}
]
},
"image": {
"id": "fake-image-id",
"links": [{
"rel": "self",
"href": "http://localhost:8080/images/1"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/images/1"
}, {
"rel": "alternate",
"href": "http://glance.api..."
}
]
},
"state": {
"current": "OFF",
"available_states": ["DEPLOYED"],
"started": "2013 - 05 - 20 12: 34: 56",
"links ": [{
"rel ": "self ",
"href ": "http: //localhost:8080/v1/nodes/1/state"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/ndoes/1/state"
}
]
},
"ports": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1/nodes/1/ports"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/ports"
}
]
},
"management_configuration": {
"type": "management_configuration",
"control": {
"driver": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1/drivers/1"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers/1"
}
]
},
"parameters": {
"ipmi_username": "admin",
"ipmi_password": "password",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/nodes/1/management_configuration/control/parameters"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters"
}
]
}
},
"deployment": {
"driver": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/drivers/1"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers/1"
}
]
},
"parameters": {
"image_source": "glance://image-uuid",
"deploy_image_source": "glance://deploy-image-uuid",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/nodes/1/management_configuration/control/parameters"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters"
}
]
}
}
}
}
Chassis
--------
Usage
^^^^^^
======= ============= ==========
Verb Path Response
======= ============= ==========
GET /chassis List chassis
GET /chassis/<id> Retrieve a specific chassis
POST /chassis Create a new chassis
PUT /chassis/<id> Update a chassis
DELETE /chassis/<id> Delete chassis and remove all associations between
nodes
======= ============= ==========
Fields
^^^^^^^
id
Unique ID for this chassis
type
The type of this resource, i.e. chassis
description
A user defined description
meta_data
This chassis's meta data see: MetaData_
nodes
A link to a collection of nodes associated with this chassis see: Node_
Example
^^^^^^^^
JSON structure of a chassis::
{
"id": "fake-chassis-id",
"type": "chassis",
"description": "data-center-1-chassis",
"meta_data": {
"data_centre": "us.east.1",
"function": "high-speed-cpu",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/chassis/1/meta-data"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/chassis/1/meta-data"
}
]
},
"nodes": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/chassis/1/nodes"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/chassis/1/nodes"
}
]
}
}
Port
-----
Usage
^^^^^^
======= ============= ==========
Verb Path Response
======= ============= ==========
GET /ports List ports
GET /ports/<id> Retrieve a specific port
POST /ports Create a new port
PUT /ports/<id> Update a port
DELETE /ports/<id> Delete port and remove all associations between nodes
======= ============= ==========
Fields
^^^^^^^
id
Unique ID for this port
type
The type of this resource, i.e. port
address
MAC Address for this port
meta_data
This port's meta data see: MetaData_
nodes
A link to the node this port belongs to see: Node_
Example
^^^^^^^^
JSON structure of a port::
{
"id": "fake-port-uuid",
"type": "port",
"address": "01:23:45:67:89:0A",
"meta-data": {
"foo": "bar",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/ports/1/meta-data"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/ports/1/meta-data"
}
]
},
"node": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/ports/1/node"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/ports/1/node"
}
]
}
}
Driver
-------
Usage
^^^^^^
======= ============= ==========
Verb Path Response
======= ============= ==========
GET /drivers List drivers
GET /drivers/<id> Retrieve a specific driver
======= ============= ==========
Fields
^^^^^^^
id
Unique ID for this driver
type
The type of this resource, i.e. driver
name
Name of this driver
function
The function this driver performs, see: DriverFunctions_
meta_data
This driver's meta data see: MetaData_
required_fields
An array containing the required fields for this driver
optional_fields
An array containing optional fields for this driver
DriverFunctions
^^^^^^^^^^^^^^^^
Drivers can have one of two types of functionality, control or deployment. You
must enter a driver or the correct function into the relevant pieces of the
management configuration resource. For example, you must enter a driver with
function "control" into the control piece of the management configuration.
Example Driver
^^^^^^^^^^^^^^^
JSON structure of a driver::
{
"id": "fake-driver-id",
"type": "driver",
"name": "ipmi",
"function": "control",
"description": "power on/off using ipmi",
"meta-data": {
"foo": "bar",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/ports/1/meta-data"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/ports/1/meta-data"
}
]
},
"required_fields": [
"ipmi_address",
"ipmi_password",
"ipmi_username"
],
"optional_fields": [
"ipmi_terminal_port",
],
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1/drivers/"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers/1"
}
]
}
Image
-------
An Image resource. This represents a disk image used for booting a Node_.
Images are not stored within Ironic, instead images are stored in glance and
can be accessed via this API.
Usage
^^^^^^
======= ============= ==========
Verb Path Response
======= ============= ==========
GET /images List images
GET /images/<id> Retrieve a specific image
======= ============= ==========
Fields
^^^^^^^
id
Unique ID for this port
type
The type of this resource, i.e. image
name
Name of this image
status
Status of the image
visibility
Whether or not this is publicly visible
size
Size of this image in MB
Checksum
MD5 Checksum of the image
Tags
Tags associated with this image
Example
^^^^^^^^
JSON structure of an image::
{
"id": "da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
"type": "image"
"name": "cirros-0.3.0-x86_64-uec-ramdisk",
"status": "active",
"visibility": "public",
"size": 2254249,
"checksum": "2cec138d7dae2aa59038ef8c9aec2390",
"tags": ["ping", "pong"],
"created_at": "2012-08-10T19:23:50Z",
"updated_at": "2012-08-10T19:23:50Z",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1/images/"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/images/1"
}, {
"rel": "alternate",
"href": "http://openstack.glance.org/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea"
}, {
"rel": "file",
"href": "http://openstack.glance.org/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file"
}
]
}
ManagementConfiguration
------------------------
The Management Configuration is a sub resource (see: SubResource_) that
contains information about how to manage a particular node.
This resource makes up part of the node resource description and can only be
accessed from within a node URL structure. For example:
/nodes/1/management_configuration. The ManagementConfiguration essentially
defines the control and deployment driver setup.
An empty management configuration resource will be created upon node creation.
Therefore only PUT and GET are defined on ManagementConfiguration resources.
Sections of the ManagementConfiguration also support GET and PUT operations.
Such as the Control, Deployment, and Parameters sections.
The Control Parameters and Deployment Parameters resources are not introspected
by Ironic; they are passed directly to the respective drivers. Each driver
defines a set of Required and Optional fields, which are validated when the
resource is set to a non-empty value. Supplying partial or invalid data will
result in an error and no data will be saved. PUT an empty resource to erase
the existing data. Changing the Control or Deployment section of the
ManagementConfiguration will erase any existing Parameter section for that
resource.
Updating both the driver and driver parameters at once is allowed.
For example::
PUT to /nodes/1/management_configuration/control
{ "id": "ipmi", "parameters": { "ipmi_username": "foo", ...} }
Management Configuration Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
======= ================================== ==========
Verb Path Response
======= ================================== ==========
GET /nodes/1/management_configuration Retrieve a node's management
configuration
PUT /nodes/1/management_configuration Update a node's management
configuration
======= ================================== ==========
Management Configuration / Control Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
======= ========================================== ==========
Verb Path Response
======= ========================================== ==========
GET /nodes/1/management_configuration/control Retrieve a node's
management control
configuration
PUT /nodes/1/management_configuration/control Update a node's
management control
configuration
======= ========================================== ==========
Management Configuration / Deployment Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
====== ============================================ ==========
Verb Path Response
====== ============================================ ==========
GET /nodes/1/management_configuration/deployment Retrieve a node's
management deployment
configuration
PUT /nodes/1/management_configuration/deployment Update a node's
management deployment
configuration
====== ============================================ ==========
Management Configuration / Control / Parameters Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
====== ===================================================== ==========
Verb Path Response
====== ===================================================== ==========
GET /nodes/1/management_configuration/control/parameters Retrieve a node's
management control
paramters
PUT /nodes/1/management_configuration/control/parameters Update a node's
management control
paramters
====== ===================================================== ==========
Management Configuration / deployment / parameters Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
====== ======================================================== ==========
Verb Path Response
====== ======================================================== ==========
GET /nodes/1/management_configuration/deployment/parameters Retrieve a node's
management deployment
paramters
PUT /nodes/1/management_configuration/deployment/parameters Update a node's
management deployment
paramters
====== ======================================================== ==========
Fields
^^^^^^^
type
The type of this resource, i.e. management_configuration, deployment,
control, parameters
control
The control sub resource for specifying node control driver and parameters
deployment
The deployment sub resource for specifying node deployment driver and
paramters
driver
Link to the driver resource for a deployment or control sub resource
paramters
The parameters sub resource responsible for setting the driver paramters
for a control or deployment. The required and optional parameters are
specified on the driver resource. see: Driver_
Example
^^^^^^^^
JSON structure of a management_configuration::
{
"type": "management_configuration",
"control": {
"driver": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1/drivers/ipmi"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers/ipmi"
}
]
},
"parameters": {
"ipmi_username": "admin",
"ipmi_password": "password",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/nodes/1/management_configuration/control/parameters"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters"
}
]
}
},
"deployment": {
"driver": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/drivers/pxe"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers/pxe"
}
]
},
"parameters": {
"image_source": "glance://image-uuid",
"deploy_image_source": "glance://deploy-image-uuid",
"links": [{
"rel": "self",
"href": "http://localhost:8080/version/1/nodes/1/management_configuration/control/parameters"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters"
}
]
}
}
}
State
------
States are sub resources (see: SubResource_) that represents the state of
either a node. The state of the node is governed by an internal state machine.
You can get the next available state code from the "available_states" array.
To change the state of the node simply set the "current" field to one of the
available states.
For example::
PUT
{
...
"current": "DEPLOYED"
...
}
Usage:
^^^^^^
======= ================================== ===========================
Verb Path Response
======= ================================== ===========================
GET /nodes/1/state Retrieve a node's state
PUT /nodes/1/state Update a node's state
======= ================================== ===========================
Fields
^^^^^^^
current
The current state (code) that this resource resides in
available_states
An array of available states this parent resource is able to transition to
from the current state
started
The time and date the resource entered the current state
Example
^^^^^^^^
JSON structure of a state::
{
"current": "OFF",
"available_states": ["DEPLOYED"],
"started": "2013 - 05 - 20 12: 34: 56",
"links ": [{
"rel ": "self ",
"href ": "http: //localhost:8080/v1/nodes/1/state"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/state"
}
]
}
MetaData
---------
MetaData is an arbitrary set of key value pairs that a client can set on a
resource which can be retrieved later. Ironic will not introspect the metadata
and does not support querying on individual keys.
Usage:
^^^^^^
======= =================== ==========
Verb Path Response
======= =================== ==========
GET /nodes/1/meta_data Retrieve a node's meta data
PUT /nodes/1/meta_data Update a node's meta data
======= =================== ==========
Fields
^^^^^^^
Fields for this resource are arbitrary.
Example
^^^^^^^^
JSON structure of a meta_data::
{
"foo": "bar"
"bar": "foo"
}
Areas To Be Defined
####################
- Discoverability of Driver State Change Parameters
- State Change in Drivers
- Advanced Queries
- Support for parallel driver actions
- Error Codes
- Security
View Git Blame Copy Permalink