Add API reference

Add initial API reference, which covers all inspector endpoits. The conf.py and the tox environment are stolen from ironic. Co-Authored-By: Kaifeng Wang <kaifeng.w@gmail.com> Change-Id: I5009e8708dcad8ab25380f7bf574125d6e758ef5
5 years ago · 05a86b3d57
23 changed files with 1459 additions and 1 deletions
--- a/api-ref/source/conf.py
+++ b/api-ref/source/conf.py
@ -0,0 +1,238 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# ironic-inspector documentation build configuration file, created by
+# sphinx-quickstart on Tue Jul 25 15:17:47 2017.
+#
+# This file is execfile()d with the current directory set to
+# its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import subprocess
+import sys
+import warnings
+
+import openstackdocstheme
+
+extensions = [
+    'os_api_ref',
+    'openstackdocstheme',
+]
+
+
+html_theme = 'openstackdocs'
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
+html_theme_options = {
+    "sidebar_dropdown": "api_ref",
+    "sidebar_mode": "toc",
+}
+html_context = {'bug_project': 'ironic-inspector', 'bug_tag': 'api-ref'}
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# openstackdocstheme options
+repository_name = 'openstack/ironic-inspector'
+use_storyboard = True
+bug_project = 'openstack/ironic-inspector'
+bug_tag = 'api-ref'
+
+# General information about the project.
+project = 'Hardware Introspection API Reference'
+copyright = '2017-present, Ironic Inspector Developers'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+from ironic_inspector.version import version_info
+# The full version, including alpha/beta/rc tags.
+release = version_info.release_string()
+# The short X.Y version.
+version = version_info.version_string()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# The reST default role (used for this markup: `text`) to use
+# for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for man page output ----------------------------------------------
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+    "-n1"]
+try:
+    html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
+except Exception:
+    warnings.warn('Cannot get last updated time from git repository. '
+                  'Not setting "html_last_updated_fmt".')
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_use_modindex = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'IronicInspectorAPIRefdoc'
+
+
+# -- Options for LaTeX output -------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     '%s.tex' % project,
+     u'OpenStack Hardware Introspection API Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@ -0,0 +1,12 @@
+:tocdepth: 2
+
+=========================================
+Hardware Introspection for Bare Metal API
+=========================================
+
+.. rest_expand_all::
+
+.. include:: introspection-api-versions.inc
+.. include:: introspection-api-v1-introspection.inc
+.. include:: introspection-api-v1-continue.inc
+.. include:: introspection-api-v1-rules.inc
--- a/api-ref/source/introspection-api-v1-continue.inc
+++ b/api-ref/source/introspection-api-v1-continue.inc
@ -0,0 +1,68 @@
+.. -*- rst -*-
+
+==========================
+Process introspection data
+==========================
+
+After the ramdisk collects the required information from the bare metal
+node, it should post it back to Inspector via ``POST /v1/continue`` method.
+
+
+.. warning::
+    Operators are reminded not to expose the Ironic Inspector API to
+    unsecured networks. Below method is available to *unauthenticated*
+    clients because **ironic-python-agent** ramdisk does not have access to
+    keystone credentials.
+
+
+Ramdisk Callback
+================
+
+.. rest_method::  POST /v1/continue
+
+It is internal method for the ramdisk to post back all discovered data.
+This should not be used for anything other than the ramdisk.
+
+Full list of hardware inventory keys may be found in **ironic-python-agent**
+documentation: `hardware inventory <https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory>`_.
+
+Normal response codes: 201
+
+Error codes: 400
+
+Request
+-------
+
+List of mandatory hardware keys:
+
+.. rest_parameters:: parameters.yaml
+
+   - inventory: inventory
+   - memory: memory
+   - cpu: cpu
+   - bmc_address: bmc_address
+   - interfaces: interfaces
+   - disks: disks
+   - root_disk: root_disk
+   - boot_interface: boot_interface
+   - logs: logs
+
+**Example node introspection continue request:**
+
+.. literalinclude:: samples/api-v1-continue-request.json
+   :language: javascript
+
+
+Response
+--------
+
+The response will contain Ironic node ``uuid`` record.
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: node_uuid
+
+**Example JSON representation:**
+
+.. literalinclude:: samples/api-v1-common-node-uuid.json
+   :language: javascript
--- a/api-ref/source/introspection-api-v1-introspection.inc
+++ b/api-ref/source/introspection-api-v1-introspection.inc
@ -0,0 +1,226 @@
+.. -*- rst -*-
+
+==================
+Node Introspection
+==================
+
+Start, abort introspection, get introspection status, get introspection data
+are done through the ``/v1/introspection`` resource. There are also several
+sub-resources, which allow further actions to be performed on introspection.
+
+Start Introspection
+===================
+
+.. rest_method::  POST /v1/introspection/{node_id}
+
+Initiate hardware introspection for node {node_id} . All power management
+configuration for this node needs to be done prior to calling the endpoint.
+
+In case missing or invalid authentication response code will be 401 and 403.
+If Inspector don't find node {node_id}, it will return 404.
+
+Normal response codes: 202
+
+Error codes: 400, 401, 403, 404
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_id: node_id
+   - manage_boot: manage_boot
+
+
+Response
+--------
+
+The response will be empty body.
+
+Get Introspection status
+========================
+
+.. rest_method::  GET /v1/introspection/{node_id}
+
+Get node introspection status.
+
+In case missing or invalid authentication response code will be 401 and 403.
+If Inspector don't find node {node_id}, it will return 404.
+
+Normal response codes: 200
+
+Error codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_id: node_id
+
+
+Response
+--------
+
+The response will contain the complete introspection info, like
+create, finish time, introspection state, errors if any.
+
+.. rest_parameters:: parameters.yaml
+
+   - error: error
+   - finished: finished
+   - finished_at: finished_at
+   - links: links
+   - started_at: started_at
+   - state: state
+   - uuid: node_id
+
+**Example JSON representation of an introspection:**
+
+.. literalinclude:: samples/api-v1-get-introspection-response.json
+   :language: javascript
+
+
+List All Introspection statuses
+===============================
+
+.. rest_method::  GET /v1/introspection/
+
+Returned status list is sorted by the ``started_at, uuid`` attribute pair,
+newer items first.
+
+In case missing or invalid authentication response code will be 401 and 403.
+
+Normal response codes: 200
+
+Error codes: 400, 401, 403
+
+Request
+-------
+
+Status list may be paginated with these query string fields:
+
+.. rest_parameters:: parameters.yaml
+
+   - marker: marker
+   - limit: limit
+
+
+Response
+--------
+
+The response will contain a list of status objects:
+
+.. rest_parameters:: parameters.yaml
+
+   - error: error
+   - finished: finished
+   - finished_at: finished_at
+   - links:  links
+   - started_at: started_at
+   - state: state
+   - uuid: node_id
+
+
+**Example JSON representation of an introspection:**
+
+.. literalinclude:: samples/api-v1-get-introspections-response.json
+   :language: javascript
+
+
+Abort Introspection
+===================
+
+.. rest_method::  POST /v1/introspection/{node_id}/abort
+
+Abort running introspection.
+
+Normal response codes: 202
+
+Error codes:
+
+* 400 - bad request
+* 401, 403 - missing or invalid authentication
+* 404 - node cannot be found
+* 409 - inspector has locked this node for processing
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_id: node_id
+
+
+Get Introspection data
+======================
+
+.. rest_method::  GET /v1/introspection/{node_id}/data
+
+Return stored data from successful introspection.
+
+.. note::
+    We do not provide any backward compatibility guarantees regarding the
+    format and contents of the stored data. Notably, it depends on the ramdisk
+    used and plugins enabled both in the ramdisk and in inspector itself.
+
+Normal response codes: 200
+
+Error codes:
+
+* 400 - bad request
+* 401, 403 - missing or invalid authentication
+* 404 - data cannot be found or data storage not configured
+
+Request
+-------
+
+Status list may be paginated with these query string fields:
+
+.. rest_parameters:: parameters.yaml
+
+   - node_id: node_id
+   - limit: limit
+
+
+Response
+--------
+
+The response will contain introspection data in the form of json string.
+
+**Example JSON representation of an introspection data:**
+
+.. literalinclude:: samples/api-v1-data-introspection-response.json
+   :language: javascript
+
+
+Reapply Introspection on stored data
+====================================
+
+.. rest_method::  POST /v1/introspection/{node_id}/data/unprocessed
+
+This method riggers introspection on stored unprocessed data.
+No data is allowed to be sent along with the request.
+
+.. note::
+
+    Requires enabling Swift store in processing section of the
+    configuration file.
+
+Normal response codes: 202
+
+Error codes:
+
+* 400 - bad request or store not configured
+* 401, 403 - missing or invalid authentication
+* 404 - node not found for Node ID
+* 409 - inspector locked node for processing
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - node_id: node_id
--- a/api-ref/source/introspection-api-v1-rules.inc
+++ b/api-ref/source/introspection-api-v1-rules.inc
@ -0,0 +1,155 @@
+.. -*- rst -*-
+
+===================
+Introspection Rules
+===================
+
+Simple JSON-based DSL to define rules, which run during introspection.
+
+
+Create Introspection Rule
+=========================
+
+.. rest_method::  POST /v1/rules
+
+Create a new introspection rule.
+
+Normal response codes:
+
+* 200 - OK for API version < 1.6
+* 201 - OK for API version 1.6 and higher
+
+Error codes:
+
+* 400 - wrong rule format
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - conditions: conditions
+    - actions: actions
+    - description: description
+
+
+**Example creating rule request:**
+
+.. literalinclude:: samples/api-v1-create-rule-request.json
+   :language: javascript
+
+Response
+--------
+
+The response will contain full rule object, also ``condition``
+section may contain additional default fields, like ``invert``,
+``multiple`` and ``field``, see ` Conditions https://docs.openstack.org/ironic-inspector/latest/user/usage.html#conditions>`_
+
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - conditions: conditions
+    - actions: actions
+    - description: description
+
+**Example JSON representation:**
+
+.. literalinclude:: samples/api-v1-create-rule-response.json
+   :language: javascript
+
+
+Get Introspection Rules
+=======================
+
+.. rest_method::  GET /v1/rules
+
+List all introspection rules
+
+Normal response codes: 200
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - description: description
+    - links: links
+
+**Example JSON representation:**
+
+.. literalinclude:: samples/api-v1-get-rules-response.json
+   :language: javascript
+
+
+Delete Introspection Rules
+==========================
+
+.. rest_method::  DELETE /v1/rules
+
+Delete all introspection rules
+
+Normal response codes: 204
+
+
+
+Get Introspection Rule
+======================
+
+.. rest_method::  GET /v1/rules/{uuid}
+
+Get one introspection rule by its ``uuid``
+
+Normal response codes: 202
+
+Error codes:
+
+* 404 - rule not found
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+
+
+Response
+--------
+
+The response will contain full rule object:
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - conditions: conditions
+    - actions: actions
+    - description: description
+
+**Example JSON representation:**
+
+.. literalinclude:: samples/api-v1-get-rule-response.json
+   :language: javascript
+
+
+Delete Introspection Rule
+=========================
+
+.. rest_method::  DELETE /v1/rules/{uuid}
+
+Delete introspection rule by ``uuid``.
+
+Normal response codes: 204
+
+Error codes:
+
+* 404 - rule not found
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
--- a/api-ref/source/introspection-api-versions.inc
+++ b/api-ref/source/introspection-api-versions.inc
@ -0,0 +1,81 @@
+.. -*- rst -*-
+
+============
+API versions
+============
+
+Concepts
+========
+
+In order to bring new features to users over time, the Ironic
+Inspector API supports versioning. There are two kinds of versions:
+
+- ``major versions``, which have dedicated urls.
+- ``microversions``, which can be requested through the use of the
+  ``X-OpenStack-Ironic-Inspector-API-Version`` header.
+
+The Version APIs work differently from other APIs as they *do not* require authentication.
+
+All API requests support the ``X-OpenStack-Ironic-Inspector-API-Version`` header.
+This header SHOULD be supplied with every request; in the absence of this header,
+server will default to current supported version in all responses.
+
+List API versions
+=================
+
+.. rest_method::  GET /
+
+This fetches all the information about all known major API versions in the
+deployment. Links to more specific information will be provided for each major
+API version, as well as information about supported min and max microversions.
+
+Normal response codes: 200
+
+Request
+-------
+
+Response Example
+----------------
+
+.. rest_parameters::  parameters.yaml
+
+    - versions: versions
+    - id: id
+    - links: links
+    - status: status
+
+    - x-openstack-ironic-api-min-version: x-openstack-ironic-inspector-api-minimum-version
+    - x-openstack-ironic-api-max-version: x-openstack-ironic-inspector-api-maximum-version
+
+.. literalinclude:: samples/api-root-response.json
+   :language: javascript
+
+
+Show v1 API
+===========
+
+.. rest_method::  GET /v1/
+
+Show all the resources within the Ironic Inspector v1 API.
+
+Normal response codes: 200
+
+Request
+-------
+
+Response Example
+----------------
+
+.. rest_parameters::  parameters.yaml
+
+    - resources: resources
+    - links: links
+    - href: href
+    - rel: rel
+    - name: name
+
+    - x-openstack-ironic-api-min-version: x-openstack-ironic-inspector-api-minimum-version
+    - x-openstack-ironic-api-max-version: x-openstack-ironic-inspector-api-maximum-version
+
+.. literalinclude:: samples/api-v1-root-response.json
+   :language: javascript
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@ -0,0 +1,257 @@
+# variables in header
+x-auth-token:
+  description: |
+    The client token being passed into Ironic Inspector API to make
+    authentication.
+  in: header
+  required: true
+  type: string
+x-openstack-ironic-inspector-api-maximum-version:
+  description: |
+    Maximum API microversion supported by this endpoint, eg. "1.10"
+  in: header
+  required: true
+  type: string
+x-openstack-ironic-inspector-api-minimum-version:
+  description: |
+    Minimum API microversion supported by this endpoint, eg. "1.1"
+  in: header
+  required: true
+  type: string
+x-openstack-ironic-inspector-api-version:
+  description: >
+    A request SHOULD include this header to indicate to the Ironic Inspector
+    API service what version the client supports. The server may transform
+    the response object into compliance with the requested version, if it is
+    supported, or return a 406 Not Supported error.
+    If this header is not supplied, the server will default to current
+    supported version in all responses.
+  in: header
+  required: true
+  type: string
+
+# variables in path
+node_id:
+  description: |
+    The UUID of the Ironic node.
+  in: path
+  required: true
+  type: string
+
+uuid:
+  description: |
+    The UUID of the Ironic Inspector rule.
+  in: path
+  required: true
+  type: string
+
+# common variables to query strings
+limit:
+  description: |
+    Requests a page size of items. Returns a number of items up to a limit
+    value. Use the ``limit`` parameter to make an initial limited request and
+    use the ID of the last-seen item from the response as the ``marker``
+    parameter value in a subsequent limited request. This value cannot be
+    larger than the ``api_max_limit`` option in the configuration. If it is
+    higher than ``api_max_limit``, return 400 Bad Request.
+  in: query
+  required: false
+  type: integer
+manage_boot:
+  description: |
+    Whether the current installation of ironic-inspector can manage PXE
+    booting of nodes.
+  in: query
+  required: false
+  type: string
+marker:
+  description: |
+    The ID of the last-seen item. Use the ``limit`` parameter to make an
+    initial limited request and use the ID of the last-seen item from the
+    response as the ``marker`` parameter value in a subsequent request.
+  in: query
+  required: false
+  type: string
+
+
+# variables to methods
+actions:
+  description: |
+    List of operations that will be performed if ``conditions`` of this
+    rule are fulfilled.
+  in: body
+  required: true
+  type: array
+bmc_address:
+  description: |
+    IP address of the node's BMC
+  in: body
+  required: false
+  type: string
+boot_interface:
+  description: |
+    MAC address of the NIC that the machine PXE booted from
+  in: body
+  required: false
+  type: string
+conditions:
+  description: |
+    List of a logic statementd or operations in rules, that can be
+    evaluated as True or False.
+  in: body
+  required: false
+  type: array
+cpu:
+  description: |
+    CPU information containing at least keys ``count`` (CPU count) and
+    ``architecture`` (CPU architecture, e.g. ``x86_64``),
+  in: body
+  required: true
+  type: string
+description:
+  description: |
+    Rule human-readable description.
+  in: body
+  required: false
+  type: string
+disks:
+  description: |
+    List of disk block devices containing at least ``name`` and ``size``
+    keys. In case ``disks`` are not provided **ironic-inspector**  assumes
+    that this is a disk-less node.
+  in: body
+  required: true
+  type: array
+error:
+  description: |
+    Error description string or ``null``;
+    ``Canceled by operator`` in case introspection was aborted.
+  in: body
+  required: true
+  type: string
+finished:
+  description: |
+    Whether introspection has finished for this node.
+  in: body
+  required: true
+  type: boolean
+finished_at:
+  description: |
+    UTC ISO8601 timestamp of introspection finished or ``null``.
+  in: body
+  required: true
+  type: string
+href:
+  description: |
+    A bookmark link to resource object.
+  in: body
+  required: true
+  type: string
+id:
+  description: |
+    API microversion, eg, "1.12".
+  in: body
+  required: true
+  type: string
+interfaces:
+  description: |
+    List of dictionaries with interfaces info, contains following keys:
+    ``name``,  ``ipv4_address``, ``mac_address``, ``client_id``.
+  in: body
+  required: true
+  type: array
+inventory:
+  description: Dictionary with hardware inventory keys.
+  in: body
+  required: true
+  type: object
+links:
+  description: |
+    A list of relative links. Includes the self and
+    bookmark links.
+  in: body
+  required: true
+  type: array
+logs:
+  description: Base64-encoded logs from the ramdisk.
+  in: body
+  required: false
+  type: string
+memory:
+  description: |
+    Memory information containing at least ``physical_mb`` key,
+    memory size is reported by dmidecod.
+  in: body
+  required: true
+  type: string
+name:
+  description: |
+    Resource name, like `introspection`, `rules`.
+  in: body
+  required: true
+  type: string
+node_uuid:
+  description: Ironic node uui
+  in: body
+  required: true
+  type: string
+rel:
+  description: |
+    The relationship between the version and the href.
+  in: body
+  required: true
+  type: string
+resources:
+  description: |
+    A list of available API resources.
+  in: body
+  required: true
+  type: array
+root_disk:
+  description: |
+    Default deployment root disk as calculated by the **ironic-python-agent**
+    algorithm.
+  in: body
+  required: true
+  type: string
+started_at:
+  description: |
+    UTC ISO8601 timestamp of introspection start.
+  in: body
+  required: true
+  type: string
+state:
+  description: |
+    Current state of the introspection, possible values:  ``enrolling``,
+    ``error``, ``finished``, ``processing``, ``reapplying``, ``starting``,
+    ``waiting``. For detail information about states see
+    `Inspector states <https://docs.openstack.org/ironic-inspector/latest/user/workflow.html#state-machine-diagram>`_.
+  in: body
+  required: true
+  type: string
+status:
+  description: |
+    The status of this API version. This can be one of:
+
+    - ``CURRENT`` This version is up to date recent and should be prioritized over all others.
+
+    - ``SUPPORTED`` This version is available and may not be updated in future.
+
+    - ``DEPRECATED`` This version is still available but may be removed in future.
+
+    - ``EXPERIMENTAL`` This version is under development and may be changed in future.
+  in: body
+  required: true
+  type: string
+version:
+  description: |
+    Versioning of this API response, eg. "1.12".
+  in: body
+  required: true
+  type: string
+versions:
+  description: |
+    Array of information about currently supported versions.
+  in: body
+  required: true
+  type: array
--- a/api-ref/source/samples/api-root-response.json
+++ b/api-ref/source/samples/api-root-response.json
@ -0,0 +1,14 @@
+{
+  "versions": [
+    {
+      "id": "1.12",
+      "links": [
+        {
+          "href": "http://127.0.0.1:5050/v1",
+          "rel": "self"
+        }
+      ],
+      "status": "CURRENT"
+    }
+  ]
+}
--- a/api-ref/source/samples/api-v1-common-node-uuid.json
+++ b/api-ref/source/samples/api-v1-common-node-uuid.json
@ -0,0 +1,3 @@
+{
+  "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
+}
--- a/api-ref/source/samples/api-v1-common-rule-uuid.json
+++ b/api-ref/source/samples/api-v1-common-rule-uuid.json
@ -0,0 +1,3 @@
+{
+  "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
+}
--- a/api-ref/source/samples/api-v1-continue-request.json
+++ b/api-ref/source/samples/api-v1-continue-request.json
@ -0,0 +1,75 @@
+{
+  "root_disk": {
+    "rotational": true,
+    "vendor": "0x1af4",
+    "name": "/dev/vda",
+    "hctl": null,
+    "wwn_vendor_extension": null,
+    "wwn_with_extension": null,
+    "model": "",
+    "wwn": null,
+    "serial": null,
+    "size": 13958643712
+  },
+  "boot_interface": "52:54:00:4e:3d:30",
+  "inventory": {
+    "bmc_address": "192.167.2.134",
+    "interfaces": [
+      {
+        "lldp": null,
+        "product": "0x0001",
+        "vendor": "0x1af4",
+        "name": "eth1",
+        "has_carrier": true,
+        "switch_port_descr": null,
+        "switch_chassis_descr": null,
+        "ipv4_address": "172.24.42.101",
+        "client_id": null,
+        "mac_address": "52:54:00:47:20:4d"
+      },
+      {
+        "lldp": null,
+        "product": "0x0001",
+        "vendor": "0x1af4",
+        "name": "eth0",
+        "has_carrier": true,
+        "switch_port_descr": null,
+        "switch_chassis_descr": null,
+        "ipv4_address": "172.24.42.100",
+        "client_id": null,
+        "mac_address": "52:54:00:4e:3d:30"
+      }
+    ],
+    "disks": [
+      {
+        "rotational": true,
+        "vendor": "0x1af4",
+        "name": "/dev/vda",
+        "hctl": null,
+        "wwn_vendor_extension": null,
+        "wwn_with_extension": null,
+        "model": "",
+        "wwn": null,
+        "serial": null,
+        "size": 13958643712
+      }
+    ],
+    "memory": {
+      "physical_mb": 2048,
+      "total": 2105864192
+    },
+    "cpu": {
+      "count": 2,
+      "frequency": "2100.084",
+      "flags": [
+        "fpu",
+        "mmx",
+        "fxsr",
+        "sse",
+        "sse2",
+        ],
+      "architecture": "x86_64"
+    }
+  },
+  "logs": "<hidden>"
+}
--- a/api-ref/source/samples/api-v1-create-rule-request.json
+++ b/api-ref/source/samples/api-v1-create-rule-request.json
@ -0,0 +1,26 @@
+{
+   "uuid":"7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
+   "description":"Set deploy info if not already set on node",
+   "actions":[
+      {
+         "action":"set-attribute",
+         "path":"driver_info/deploy_kernel",
+         "value":"8fd65-c97b-4d00-aa8b-7ed166a60971"
+      },
+      {
+         "action":"set-attribute",
+         "path":"driver_info/deploy_ramdisk",
+         "value":"09e5420c-6932-4199-996e-9485c56b3394"
+      }
+   ],
+   "conditions":[
+      {
+         "op":"is-empty",
+         "field":"node://driver_info.deploy_ramdisk"
+      },
+      {
+         "op":"is-empty",
+         "field":"node://driver_info.deploy_kernel"
+      }
+   ]
+}
--- a/api-ref/source/samples/api-v1-create-rule-response.json
+++ b/api-ref/source/samples/api-v1-create-rule-response.json
@ -0,0 +1,36 @@
+{
+  "actions": [
+    {
+      "action": "set-attribute",
+      "path": "driver_info/deploy_kernel",
+      "value": "8fd65-c97b-4d00-aa8b-7ed166a60971"
+    },
+    {
+      "action": "set-attribute",
+      "path": "driver_info/deploy_ramdisk",
+      "value": "09e5420c-6932-4199-996e-9485c56b3394"
+    }
+  ],
+  "conditions": [
+    {
+      "field": "node://driver_info.deploy_ramdisk",
+      "invert": false,
+      "multiple": "any",
+      "op": "is-empty"
+    },
+    {
+      "field": "node://driver_info.deploy_kernel",
+      "invert": false,
+      "multiple": "any",
+      "op": "is-empty"
+    }
+  ],
+  "description": "Set deploy info if not already set on node",
+  "links": [
+    {
+      "href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
+      "rel": "self"
+    }
+  ],
+  "uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c"
+}
--- a/api-ref/source/samples/api-v1-data-introspection-response.json
+++ b/api-ref/source/samples/api-v1-data-introspection-response.json
@ -0,0 +1,114 @@
+{
+   "cpu_arch":"x86_64",
+   "macs":[
+      "52:54:00:4e:3d:30"
+   ],
+   "root_disk":{
+      "rotational":true,
+      "vendor":"0x1af4",
+      "name":"/dev/vda",
+      "hctl":null,
+      "wwn_vendor_extension":null,
+      "wwn_with_extension":null,
+      "model":"",
+      "wwn":null,
+      "serial":null,
+      "size":13958643712
+   },
+   "interfaces":{
+      "eth0":{
+         "ip":"172.24.42.100",
+         "mac":"52:54:00:4e:3d:30",
+         "pxe":true,
+         "client_id":null
+      }
+   },
+   "cpus":2,
+   "boot_interface":"52:54:00:4e:3d:30",
+   "memory_mb":2048,
+   "ipmi_address":"192.167.2.134",
+   "inventory":{
+      "bmc_address":"192.167.2.134",
+      "interfaces":[
+         {
+            "lldp":null,
+            "product":"0x0001",
+            "vendor":"0x1af4",
+            "name":"eth1",
+            "has_carrier":true,
+            "switch_port_descr":null,
+            "switch_chassis_descr":null,
+            "ipv4_address":"172.24.42.101",
+            "client_id":null,
+            "mac_address":"52:54:00:47:20:4d"
+         },
+         {
+            "lldp":null,
+            "product":"0x0001",
+            "vendor":"0x1af4",
+            "name":"eth0",
+            "has_carrier":true,
+            "switch_port_descr":null,
+            "switch_chassis_descr":null,
+            "ipv4_address":"172.24.42.100",
+            "client_id":null,
+            "mac_address":"52:54:00:4e:3d:30"
+         }
+      ],
+      "disks":[
+         {
+            "rotational":true,
+            "vendor":"0x1af4",
+            "name":"/dev/vda",
+            "hctl":null,
+            "wwn_vendor_extension":null,
+            "wwn_with_extension":null,
+            "model":"",
+            "wwn":null,
+            "serial":null,
+            "size":13958643712
+         }
+      ],
+      "boot":{
+         "current_boot_mode":"bios",
+         "pxe_interface":"52:54:00:4e:3d:30"
+      },
+      "system_vendor":{
+         "serial_number":"Not Specified",
+         "product_name":"Bochs",
+         "manufacturer":"Bochs"
+      },
+      "memory":{
+         "physical_mb":2048,
+         "total":2105864192
+      },
+      "cpu":{
+         "count":2,
+         "frequency":"2100.084",
+      "flags": [
+        "fpu",
+        "mmx",
+        "fxsr",
+        "sse",
+        "sse2"
+        ],
+         "architecture":"x86_64"
+      }
+   },
+   "error":null,
+   "local_gb":12,
+   "all_interfaces":{
+      "eth1":{
+         "ip":"172.24.42.101",
+         "mac":"52:54:00:47:20:4d",
+         "pxe":false,
+         "client_id":null
+      },
+      "eth0":{
+         "ip":"172.24.42.100",
+         "mac":"52:54:00:4e:3d:30",
+         "pxe":true,
+         "client_id":null
+      }
+   }
+}
--- a/api-ref/source/samples/api-v1-get-introspection-response.json
+++ b/api-ref/source/samples/api-v1-get-introspection-response.json
@ -0,0 +1,14 @@
+{
+  "error": null,
+  "finished": true,
+  "finished_at": "2017-08-16T12:24:30",
+  "links": [
+    {
+      "href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b",
+      "rel": "self"
+    }
+  ],
+  "started_at": "2017-08-16T12:22:01",
+  "state": "finished",
+  "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
+}
--- a/api-ref/source/samples/api-v1-get-introspections-response.json
+++ b/api-ref/source/samples/api-v1-get-introspections-response.json
@ -0,0 +1,32 @@
+{
+  "introspection": [
+    {
+      "error": null,
+      "finished": true,
+      "finished_at": "2017-08-17T11:36:16",
+      "links": [
+        {
+          "href": "http://127.0.0.1:5050/v1/introspection/05ccda19-581b-49bf-8f5a-6ded99701d87",
+          "rel": "self"
+        }
+      ],
+      "started_at": "2017-08-17T11:33:43",
+      "state": "finished",
+      "uuid": "05ccda19-581b-49bf-8f5a-6ded99701d87"
+    },
+    {
+      "error": null,
+      "finished": true,
+      "finished_at": "2017-08-16T12:24:30",
+      "links": [
+        {
+          "href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b",
+          "rel": "self"
+        }
+      ],
+      "started_at": "2017-08-16T12:22:01",
+      "state": "finished",
+      "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
+    }
+  ]
+}
--- a/api-ref/source/samples/api-v1-get-rule-response.json
+++ b/api-ref/source/samples/api-v1-get-rule-response.json
@ -0,0 +1,41 @@
+{
+  "actions": [
+    {
+      "action": "set-attribute",
+      "path": "driver",
+      "value": "agent_ipmitool"
+    },
+    {
+      "action": "set-attribute",
+      "path": "driver_info/ipmi_username",
+      "value": "username"
+    },
+    {
+      "action": "set-attribute",
+      "path": "driver_info/ipmi_password",
+      "value": "password"
+    }
+  ],
+  "conditions": [
+    {
+      "field": "node://driver_info.ipmi_password",
+      "invert": false,
+      "multiple": "any",
+      "op": "is-empty"
+    },
+    {
+      "field": "node://driver_info.ipmi_username",
+      "invert": false,
+      "multiple": "any",
+      "op": "is-empty"
+    }
+  ],
+  "description": "Set IPMI driver_info if no credentials",
+  "links": [
+    {
+      "href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a",
+      "rel": "self"
+    }
+  ],
+  "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
+}
--- a/api-ref/source/samples/api-v1-get-rules-response.json
+++ b/api-ref/source/samples/api-v1-get-rules-response.json
@ -0,0 +1,24 @@
+{
+  "rules": [
+    {
+      "description": "Set deploy info if not already set on node",
+      "links": [
+        {
+          "href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
+          "rel": "self"
+        }
+      ],
+      "uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c"
+    },
+    {
+      "description": "Set IPMI driver_info if no credentials",
+      "links": [
+        {
+          "href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a",
+          "rel": "self"
+        }
+      ],
+      "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
+    }
+  ]
+}
--- a/api-ref/source/samples/api-v1-root-response.json
+++ b/api-ref/source/samples/api-v1-root-response.json
@ -0,0 +1,31 @@
+{
+  "resources": [
+    {
+      "links": [
+        {
+          "href": "http://127.0.0.1:5050/v1/introspection",
+          "rel": "self"
+        }
+      ],
+      "name": "introspection"
+    },
+    {
+      "links": [
+        {
+          "href": "http://127.0.0.1:5050/v1/continue",
+          "rel": "self"
+        }
+      ],
+      "name": "continue"
+    },
+    {
+      "links": [
+        {
+          "href": "http://127.0.0.1:5050/v1/rules",
+          "rel": "self"
+        }
+      ],
+      "name": "rules"
+    }
+  ]
+}
--- a/lower-constraints.txt
+++ b/lower-constraints.txt
@ -56,6 +56,7 @@ netaddr==0.7.18
 netifaces==0.10.6
 openstackdocstheme==1.18.1
 openstacksdk==0.12.0
+os-api-ref==1.4.0
 os-client-config==1.29.0
 os-service-types==1.2.0
 os-testr==1.0.0
--- a/test-requirements.txt
+++ b/test-requirements.txt
@ -8,10 +8,10 @@ hacking>=1.0.0,<1.2.0 # Apache-2.0
 mock>=2.0.0 # BSD
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
 openstackdocstheme>=1.18.1 # Apache-2.0
+os-api-ref>=1.4.0 # Apache-2.0
 stestr>=1.0.0 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
 fixtures>=3.0.0 # Apache-2.0/BSD
 testresources>=2.0.0 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 oslotest>=3.2.0 # Apache-2.0
-
--- a/tox.ini
+++ b/tox.ini
@ -19,6 +19,12 @@ passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY
 basepython = python3
 commands = {posargs}

+[testenv:api-ref]
+basepython = python3
+whitelist_externals = bash
+commands =
+  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+
 [testenv:releasenotes]
 basepython = python3
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
--- a/zuul.d/legacy-ironic-inspector-jobs.yaml
+++ b/zuul.d/legacy-ironic-inspector-jobs.yaml
@ -15,6 +15,7 @@
    irrelevant-files:
      - ^test-requirements.txt$
      - ^.*\.rst$
+      - ^api-ref/.*$
      - ^doc/.*$
      - ^ironic_inspector/test/(?!.*tempest).*$
      - ^ironic_inspector/locale/.*$