From f5e074c9e4165cf3d6c6957a38809d409b0a7a73 Mon Sep 17 00:00:00 2001 From: Abhishek Kekane Date: Thu, 20 Apr 2017 18:24:06 +0530 Subject: [PATCH] Masakari API Specifications Added api specifications for versions, segments, hosts and notifications as per OpenStack standards. Change-Id: Iefc83254e22fc31d1f0d13f52e71d42c63e82b7d --- api-ref/source/conf.py | 241 ++++++++++ api-ref/source/failover-segments.inc | 329 ++++++++++++++ api-ref/source/hosts.inc | 349 +++++++++++++++ api-ref/source/index.rst | 15 + api-ref/source/notifications.inc | 225 ++++++++++ api-ref/source/parameters.yaml | 417 ++++++++++++++++++ api-ref/source/status.yaml | 62 +++ api-ref/source/versions.inc | 106 +++++ doc/api_samples/hosts/host-create-req.json | 7 + doc/api_samples/hosts/host-create-resp.json | 28 ++ doc/api_samples/hosts/host-get-resp.json | 28 ++ doc/api_samples/hosts/host-update-req.json | 5 + doc/api_samples/hosts/host-update-resp.json | 28 ++ doc/api_samples/hosts/hosts-list-resp.json | 30 ++ .../host-notification-create-req.json | 12 + .../host-notification-create-resp.json | 19 + .../notifications/notifcations-list-resp.json | 20 + .../notifications/notification-get-resp.json | 19 + .../process-notification-create-req.json | 11 + .../process-notification-create-resp.json | 18 + .../vm-notification-create-req.json | 12 + .../vm-notification-create-resp.json | 19 + .../segments/segment-create-req.json | 7 + .../segments/segment-create-resp.json | 14 + .../segments/segment-get-resp.json | 14 + .../segments/segment-update-req.json | 5 + .../segments/segment-update-resp.json | 14 + .../segments/segments-list-resp.json | 16 + .../versions/v1-version-get-resp.json | 26 ++ .../versions/versions-get-resp.json | 17 + test-requirements.txt | 2 + tox.ini | 7 + 32 files changed, 2122 insertions(+) create mode 100644 api-ref/source/conf.py create mode 100644 api-ref/source/failover-segments.inc create mode 100644 api-ref/source/hosts.inc create mode 100644 api-ref/source/index.rst create mode 100644 api-ref/source/notifications.inc create mode 100644 api-ref/source/parameters.yaml create mode 100644 api-ref/source/status.yaml create mode 100644 api-ref/source/versions.inc create mode 100644 doc/api_samples/hosts/host-create-req.json create mode 100644 doc/api_samples/hosts/host-create-resp.json create mode 100644 doc/api_samples/hosts/host-get-resp.json create mode 100644 doc/api_samples/hosts/host-update-req.json create mode 100644 doc/api_samples/hosts/host-update-resp.json create mode 100644 doc/api_samples/hosts/hosts-list-resp.json create mode 100644 doc/api_samples/notifications/host-notification-create-req.json create mode 100644 doc/api_samples/notifications/host-notification-create-resp.json create mode 100644 doc/api_samples/notifications/notifcations-list-resp.json create mode 100644 doc/api_samples/notifications/notification-get-resp.json create mode 100644 doc/api_samples/notifications/process-notification-create-req.json create mode 100644 doc/api_samples/notifications/process-notification-create-resp.json create mode 100644 doc/api_samples/notifications/vm-notification-create-req.json create mode 100644 doc/api_samples/notifications/vm-notification-create-resp.json create mode 100644 doc/api_samples/segments/segment-create-req.json create mode 100644 doc/api_samples/segments/segment-create-resp.json create mode 100644 doc/api_samples/segments/segment-get-resp.json create mode 100644 doc/api_samples/segments/segment-update-req.json create mode 100644 doc/api_samples/segments/segment-update-resp.json create mode 100644 doc/api_samples/segments/segments-list-resp.json create mode 100644 doc/api_samples/versions/v1-version-get-resp.json create mode 100644 doc/api_samples/versions/versions-get-resp.json diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 00000000..0de1d7d4 --- /dev/null +++ b/api-ref/source/conf.py @@ -0,0 +1,241 @@ +# Copyright (c) 2017 NTT Data +# All Rights Reserved. +# 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. +# +# masakari documentation build configuration file. +# +# 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', +] + + +html_theme = 'openstackdocs' +html_theme_path = [openstackdocstheme.get_html_theme_path()] +html_theme_options = { + "sidebar_mode": "toc", +} +html_context = {'bug_project': 'masakari', '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' + +# General information about the project. +project = u'Masakari API Reference' +copyright = u'2017-present, OpenStack Foundation' + +# 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 masakari.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 +# " v 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.Popen( + git_cmd, stdout=subprocess.PIPE).communicate()[0].decode() +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 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 = 'masakaridoc' + + # -- 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', 'Masakari.tex', + u'OpenStack Masakari 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 diff --git a/api-ref/source/failover-segments.inc b/api-ref/source/failover-segments.inc new file mode 100644 index 00000000..32b2bc9b --- /dev/null +++ b/api-ref/source/failover-segments.inc @@ -0,0 +1,329 @@ +.. -*- rst -*- + +============================ + FailoverSegments (segments) +============================ + +**Segments** + +System can be zoned from top to down levels, into Regions, Availability Zones +and Host Aggregates (or Cells). Within those zones, one or more +pacemaker/pacemaker-remote clusters may exist. In addition to those boundaries, +shared storage boundary is also important to decide the optimal host for +fail-over. Openstack zoned boundaries (such as Regions, AZ, Host Aggregates, +etc..) can be managed by the nova scheduler. However, shared storage +boundaries are difficult to manage. Moreover, the operator may want to use +other types of boundary such as rack layout and powering. Therefore, operator +may want to define the segment of hypervisor hosts and assign the failover +host/hosts for each of them. Those segment can be define based on the shared +storage boundaries or any other limitations may critical for selection of the +failover host. + +Lists, creates, shows details for, updates, and deletes segments. + +List FailoverSegments +===================== + +.. rest_method:: GET /segments + +Lists IDs, names, description, recovery_method, service_type for all segments. + +Segments contains `service_type` and `recovery_method` attributes. +`service_type` attribute indicates for which service (e.g. compute, cinder +etc) this segment belongs to. `recovery_method` attribute indicates the +recovery action to be followed when any host in a segment goes down. The +possible `recovery_method` values are: + +- ``AUTO``. Auto recovery action. +- ``RESEVED_HOST``. Reserved host recovery action. +- ``AUTO_PRIORITY``. First executes auto and if auto fails then retried with + reserved host recover action. +- ``RH_PRIORITY``. First executes reserved host and if it fails then retried + with reserved host recover action. + +You can filter on the `service_type` and `recovery_method` when you complete a +list segments request. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - marker: marker + - recovery_method: recovery_method_query_segment + - service_type: service_type_query_segment + - sort_dir: sort_dir + - sort_key: sort_key_segment + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - segments: segments + - name: segment_name + - uuid: segment_uuid + +**Example List Segments** + +.. literalinclude:: ../../doc/api_samples/segments/segments-list-resp.json + :language: javascript + + +Create Segment +============== + +.. rest_method:: POST /segments + +Creates a segment. + +Creates a FailoverSegment with name, description, service_type and +recovery_method. For `service_type` user can mention the name of service for +which this segment is created. As of now user can mention `COMPUTE` as +`service_type`. For `recovery_method` user can mention either `AUTO`, +`RESERVED_HOST`, `AUTO_PRIORITY` or `RH_PRIORITY`. Segment name should be +unique. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 409 + +.. + + A conflict(409) is returned if segment with same name is already present. + +Request +------- + +.. rest_parameters:: parameters.yaml + + + - sgement: segment + - description: segment_description + - name: segment_name + - recovery_method: segment_recovery_method + - service_type: segment_service_type + +**Example Create Segment** + +.. literalinclude:: ../../doc/api_samples/segments/segment-create-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - segment: segment + - created: created + - description: segment_description + - id: segment_id + - name: segment_name + - recovery_method: segment_recovery_method + - service_type: segment_service_type + - updated: updated + - uuid: segment_uuid + +**Example Create Segment** + +.. literalinclude:: ../../doc/api_samples/segments/segment-create-resp.json + :language: javascript + + +Show Segment Details +==================== + +.. rest_method:: GET /segments/{segment_id} + +Shows details for a segment. + +**Preconditions** + +The segment must exist. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - segment_id: segment_id_path + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - segment: segment + - created: created + - description: segment_description + - id: segment_id + - name: segment_name + - recovery_method: segment_recovery_method + - service_type: segment_service_type + - updated: updated + - uuid: segment_uuid + +**Example Show Segment Details** + +.. literalinclude:: ../../doc/api_samples/segments/segment-get-resp.json + :language: javascript + + +Update Segment +============== + +.. rest_method:: PUT /segments/{segment_id} + +Updates the editable attributes of an existing host. + +**Preconditions** + +- The segment must exist. +- User can not update segment if any host from the segment has any usage in + the notification table i.e. any host from the failover segment has + notification status as new/error/running. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + +.. + + A conflict(409) is returned if user tries to update segment name which is + already assigned to segment or if any host from the segment has any usage in + the notification table i.e. any host from the failover segment has + notification status as new/error/running. + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - segment_id: segment_id_path + - description: segment_description + - name: segment_name + - recovery_method: segment_recovery_method + - service_type: segment_service_type + +**Example Update segment name** + +.. literalinclude:: ../../doc/api_samples/segments/segment-update-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - segment: segment + - created: created + - description: segment_description + - id: segment_id + - name: segment_name + - recovery_method: segment_recovery_method + - service_type: segment_service_type + - updated: updated + - uuid: segment_uuid + +**Example Update Segment name** + +.. literalinclude:: ../../doc/api_samples/segments/segment-update-resp.json + :language: javascript + + +Delete Segment +============== + +.. rest_method:: DELETE /segments/{segment_id} + +Deletes a segment. + +**Preconditions** + +- The segment must exist. +- User can not delete segment if any host from the segment has any usage in + the notification table i.e. any host from the failover segment has + notification status as new/error/running. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + +.. + + A conflict(409) is returned if user tries to delete the segment if any host + from the segment has any usage in the notification table i.e. any host from + the failover segment has notification status as new/error/running. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - segment_id: segment_id_path + +Response +-------- + +There is no body content for the response of a successful DELETE query. \ No newline at end of file diff --git a/api-ref/source/hosts.inc b/api-ref/source/hosts.inc new file mode 100644 index 00000000..5ba9c4e8 --- /dev/null +++ b/api-ref/source/hosts.inc @@ -0,0 +1,349 @@ +.. -*- rst -*- + +============== + Hosts (hosts) +============== + +**Hosts** + +A host belongs to segment. Host can be any kind of virtual machine which can +have compute service running on it. + +Lists, creates, shows details for, updates, and deletes hosts. + +List Hosts +========== + +.. rest_method:: GET /segments/{segment_id}/hosts + +Lists IDs, names, type, reserved, on_maintenance for all hosts. + +You can filter on the type, on_maintenance and reserved when you +complete a list hosts request. + +**Preconditions** + +The segment must exist. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - segment_id: segment_id_path + - limit: limit + - marker: marker + - on_maintenance: on_maintenance_query_host + - reserved: reserved_query_host + - sort_dir: sort_dir + - sort_key: sort_key_host + - type: type_query_host + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - hosts: hosts + - name: host_name + - uuid: host_uuid + - failover_segment_id: segment_uuid + - deleted: deleted + - on_maintenance: on_maintenance + - reserved: reserved + - created_at: created + - control_attributes: control_attributes + - updated_at: updated + - failover_segment: segment + - type: host_type + - id: host_id + +**Example List hosts** + +.. literalinclude:: ../../doc/api_samples/hosts/hosts-list-resp.json + :language: javascript + + +Create Host +=========== + +.. rest_method:: POST /segments/{segment_id}/hosts + +Creates a host under given segment. + +Creates a Host under given segment with name, type, control_attributes. +User can set sepcific hosts as reserved by setting reserved attribute to True. +By default `on_maintenance` mode which indicates whether host is under +maintenance or not is False when host is created. + +**Preconditions** + +The segment must exist. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + +.. + + A conflict(409) is returned if host with same name is already present under + given segment. + +Request +------- + +.. rest_parameters:: parameters.yaml + + + - segment_id: segment_id_path + - host: host + - type: host_type + - name: host_name + - reserved: reserved + - on_maintenance: on_maintenance + +**Example Create Host** + +.. literalinclude:: ../../doc/api_samples/hosts/host-create-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - host: host + - name: host_name + - uuid: host_uuid + - failover_segment_id: segment_uuid + - deleted: deleted + - on_maintenance: on_maintenance + - reserved: reserved + - created_at: created + - control_attributes: control_attributes + - updated_at: updated + - failover_segment: segment + - type: host_type + - id: host_id + +**Example Create Host** + +.. literalinclude:: ../../doc/api_samples/hosts/host-create-resp.json + :language: javascript + + +Show Host Details +================= + +.. rest_method:: GET /segments/{segment_id}/hosts/{host_id} + +Shows details for a host. + +**Preconditions** + +The segment must exist. +The host must exist. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - segment_id: segment_id_path + - host_id: host_id_path + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - host: host + - name: host_name + - uuid: host_uuid + - failover_segment_id: segment_uuid + - deleted: deleted + - on_maintenance: on_maintenance + - reserved: reserved + - created_at: created + - control_attributes: control_attributes + - updated_at: updated + - failover_segment: segment + - type: host_type + - id: host_id + +**Example Show Host Details** + +.. literalinclude:: ../../doc/api_samples/hosts/host-get-resp.json + :language: javascript + + +Update Host +=========== + +.. rest_method:: PUT /segments/{segment_id}hosts/{host_id} + +Updates the editable attributes of an existing host. + +**Preconditions** + +- The segment must exist. +- The host must exist. +- User can not update host if that host or any host from + the failover segment has any usage in the notification + table i.e. any host from the failover segment has + notification status as new/error/running. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + +.. + + A conflict(409) is returned if user tries to update host name which is + already assigned to host under given segment or user tries to update the + host or any other host from the failover segment has any usage in the + notification table i.e. any host from the failover segment has + notification status as new/error/running. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - segment_id: segment_id_path + - host_id: host_id_path + - type: host_type + - name: segment_name + - on_maintenance: on_maintenance + - reserved: reserved + +**Example Update host reserved flag** + +.. literalinclude:: ../../doc/api_samples/hosts/host-update-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - host: host + - name: host_name + - uuid: host_uuid + - failover_segment_id: segment_uuid + - deleted: deleted + - on_maintenance: on_maintenance + - reserved: reserved + - created_at: created + - control_attributes: control_attributes + - updated_at: updated + - failover_segment: segment + - type: host_type + - id: host_id + +**Example Update host reserved flag** + +.. literalinclude:: ../../doc/api_samples/hosts/host-update-resp.json + :language: javascript + + +Delete Host +=========== + +.. rest_method:: DELETE /segments/{segment_id}hosts/{host_id} + +Deletes a host from given segment. + +**Preconditions** + +- The segment must exist. +- The host must exist. +- User can not delete host if that host or any host from + the failover segment has any usage in the notification + table i.e. any host from the failover segment has + notification status as new/error/running. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + +.. + + A conflict(409) is returned if user tries to delete the + host or any other host from the failover segment has any usage in the + notification table i.e. any host from the failover segment has + notification status as new/error/running. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - segment_id: segment_id_path + - host_id: host_id_path + + +Response +-------- + +There is no body content for the response of a successful DELETE query. \ No newline at end of file diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 00000000..ccb2b7fa --- /dev/null +++ b/api-ref/source/index.rst @@ -0,0 +1,15 @@ +:tocdepth: 2 + +============== + Masakari API +============== + +This is a reference for the OpenStack Masakari API which is provided by the +Masakari project. + +.. rest_expand_all:: + +.. include:: versions.inc +.. include:: failover-segments.inc +.. include:: hosts.inc +.. include:: notifications.inc diff --git a/api-ref/source/notifications.inc b/api-ref/source/notifications.inc new file mode 100644 index 00000000..a52dc991 --- /dev/null +++ b/api-ref/source/notifications.inc @@ -0,0 +1,225 @@ +.. -*- rst -*- + +============================== + Notifications (notifications) +============================== + +**Notifications** + +A notification is a kind of alert provided by monitoring services +(masakari-monitors) for failure of either host, process or instance. + +Lists, creates and shows details for notifications. + +List Notifications +================== + +.. rest_method:: GET /notifications + +Lists IDs, notification types, host_name, generated_time, payload and status +for all notifications. + +Notifications contain a `status` attribute that indicates the current +notification state. You can filter on the notification `status` when you +complete a list notifications request. The notification `status` is returned +in the response body. The possible notification `status` values are: + +- ``NEW``. The notification is in new state and yet to be processed. +- ``RUNNING``. The notification is in progress. +- ``FINISHED``. The notification is completed successfully. +- ``ERROR``. The notification is ended up in error. +- ``FAILED``. The notification is not processed successfully after failed once. +- ``IGNORED``. The notification is ignored by masakari engine. + +You can also filter on the basis of `source_host_uuid`, `generated_since` and +`type` when you complete a list notifications request. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - generated_since: generated_since_query_notifications + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key_notification + - source_host_uuid: source_host_uuid_query_notifications + - type: type_query_notifications + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - notifications: notifications + - notification_uuid: notification_uuid + - deleted: deleted + - created_at: created + - updated_at: updated + - status: notification_status + - uuid: notification_uuid + - source_host_uuid: source_host_uuid + - generated_time: generated_time + - type: notification_type + - payload: notification_payload + - id: notification_id + + +**Example List Notifications** + +.. literalinclude:: ../../doc/api_samples/notifications/notifcations-list-resp.json + :language: javascript + + +Create Notification +=================== + +.. rest_method:: POST /notifications + +Creates a notiification. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 409 + +.. + + A conflict(409) is returned if notification with same payload is exists or + host for which notification is generated is under maintenance. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - notification: notification + - type: notification_type + - generated_time: generated_time + - payload: notification_payload + - host_name: notification_host_name + +**Example create Process failure notification** + +.. literalinclude:: ../../doc/api_samples/notifications/process-notification-create-req.json + :language: javascript + +**Example create VM failure notification** + +.. literalinclude:: ../../doc/api_samples/notifications/vm-notification-create-req.json + :language: javascript + +**Example create COMPUTE_HOST failure notification** + +.. literalinclude:: ../../doc/api_samples/notifications/host-notification-create-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - notification: notification + - type: notification_type + - generated_time: generated_time + - payload: notification_payload + - source_host_uuid: source_host_uuid + - uuid: notification_uuid + - deleted: deleted + - created_at: created + - status: notification_status + - updated_at: updated + - id: notification_id + +**Example create Process failure notification** + +.. literalinclude:: ../../doc/api_samples/notifications/process-notification-create-resp.json + :language: javascript + +**Example create VM failure notification** + +.. literalinclude:: ../../doc/api_samples/notifications/vm-notification-create-resp.json + :language: javascript + +**Example create COMPUTE_HOST failure notification** + +.. literalinclude:: ../../doc/api_samples/notifications/host-notification-create-resp.json + :language: javascript + + +Show Notification Details +========================= + +.. rest_method:: GET /notifications/{notification_id} + +Shows details for a notification. + +**Preconditions** + +The notification must exist. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - notification_id: notification_id_path + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - notification: notification + - type: notification_type + - generated_time: generated_time + - payload: notification_payload + - source_host_uuid: source_host_uuid + - uuid: notification_uuid + - deleted: deleted + - created_at: created + - status: notification_status + - updated_at: updated + - id: notification_id + +**Example Show Notification Details** + +.. literalinclude:: ../../doc/api_samples/notifications/notification-get-resp.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 00000000..f558076c --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -0,0 +1,417 @@ +# variables in path +api_version: + in: path + required: true + type: string + description: > + The API version as returned in the links from the ``GET /`` call. +host_id_path: + description: | + The UUID of the host. + in: path + required: true + type: string +notification_id_path: + description: | + The UUID of the notification. + in: path + required: true + type: string +segment_id_path: + description: | + The UUID of the segment. + in: path + required: true + type: string + +# variables in query +generated_since_query_notifications: + description: | + Filter the notifications list result by notification generated time. + in: query + required: false + type: string +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. + in: query + required: false + type: integer +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 limited request. + in: query + required: false + type: string +on_maintenance_query_host: + description: | + Filter the host list result by on_maintenance. + in: query + required: false + type: boolean +recovery_method_query_segment: + description: | + Filter the segment list result by recovery_method. + in: query + required: false + type: string +reserved_query_host: + description: | + Filter the host list result by reserved flag. + in: query + required: false + type: boolean +service_type_query_segment: + description: | + Filter the segment list result by service_type. + in: query + required: false + type: string +sort_dir: + description: | + Sort direction. A valid value is ``asc`` (ascending) or ``desc`` (descending). + Default is ``desc``. You can specify multiple pairs of sort key and sort direction + query parameters. If you omit the sort direction in a pair, the API uses the natural + sorting direction of the direction of the segment ``sort_key`` attribute. + in: query + required: false + type: string +sort_key_host: + description: | + Sorts by a hosts attribute. Default attribute is ``created``. You can specify + multiple pairs of sort key and sort direction query parameters. If you omit the + sort direction in a pair, the API uses the natural sorting direction of the segment + ``sort_key`` attribute. The sort keys are limited to: + + - ``created_at`` + - ``type`` + - ``name`` + - ``updated_at`` + - ``uuid`` + - ``reserved`` + - ``on_maintenance`` + in: query + required: false + type: string +sort_key_notification: + description: | + Sorts by a notification attribute. Default attribute is ``created``. You can specify + multiple pairs of sort key and sort direction query parameters. If you omit the + sort direction in a pair, the API uses the natural sorting direction of the segment + ``sort_key`` attribute. The sort keys are limited to: + + - ``created_at`` + - ``type`` + - ``generated_time`` + - ``updated_at`` + - ``uuid`` + - ``payload`` + - ``status`` + - ``source_host_uuid`` + in: query + required: false + type: string +sort_key_segment: + description: | + Sorts by a segment attribute. Default attribute is ``created``. You can specify + multiple pairs of sort key and sort direction query parameters. If you omit the + sort direction in a pair, the API uses the natural sorting direction of the segment + ``sort_key`` attribute. The sort keys are limited to: + + - ``created_at`` + - ``description`` + - ``name`` + - ``updated_at`` + - ``uuid`` + - ``recovery_method`` + - ``service_type`` + in: query + required: false + type: string +source_host_uuid_query_notifications: + description: | + Filter the notifications list result by source_host_uuid. + in: query + required: false + type: string +type_query_host: + description: | + Filter the host list result by type of host. + in: query + required: false + type: boolean +type_query_notifications: + description: | + Filter the notifications list result by notification type. + in: query + required: false + type: string + +# variables in body +control_attributes: + description: | + Attributes to control host. + in: body + required: true + type: string +created: + description: | + The date and time when the resource was created. The date and time + stamp format is `ISO 8601 `_ + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2017-04-21T09:49:58-05:00``. The ``±hh:mm`` + value, if included, is the time zone as an offset from UTC. In + the previous example, the offset value is ``-05:00``. + in: body + required: true + type: string +deleted: + description: | + A boolean indicates whether this resource is deleted or not, if it has + not been deleted, ``false`` will appear. + in: body + required: true + type: boolean +generated_time: + description: | + The date and time when the notification was created. The date and time + stamp format is `ISO 8601 `_ + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2017-04-21T09:49:58-05:00``. The ``±hh:mm`` + value, if included, is the time zone as an offset from UTC. In + the previous example, the offset value is ``-05:00``. + in: body + required: true + type: string +host: + description: | + A ``host`` object. + in: body + required: true + type: object +host_id: + description: | + ID of host. + in: body + required: true + type: string +host_name: + description: | + The host name. + in: body + required: true + type: string +host_type: + description: | + Type of host. + in: body + required: true + type: string +host_uuid: + description: | + The UUID of the host. + in: body + required: true + type: string +hosts: + description: | + A list of ``host`` objects. + in: body + required: true + type: array +links: + description: | + Links to the resources in question. + in: body + required: true + type: array +notification: + description: | + A ``notification`` object. + in: body + required: true + type: object +notification_host_name: + description: | + A name of host for which notification is created. + in: body + required: true + type: object +notification_id: + description: | + ID of notification. + in: body + required: true + type: string +notification_payload: + description: | + Payload for notification. + + .. note:: This is a JSON string. + in: body + required: true + type: string +notification_status: + description: | + The notification status. + in: body + required: true + type: string +notification_type: + description: | + Type of notification, can be either ``PROCESS``, ``COMPUTE_HOST`` or ``VM``. + in: body + required: true + type: string +notification_uuid: + description: | + The UUID of the notification. + in: body + required: true + type: string +notifications: + description: | + A list of ``notification`` objects. + in: body + required: true + type: array +on_maintenance: + description: | + A boolean indicates whether this host is on maintenance or not, if it is + not on maintenance mode, ``false`` will appear. + in: body + required: false + type: boolean +reserved: + description: | + A boolean indicates whether this host is reserved or not, if it is + not reserved, ``false`` will appear. + in: body + required: false + type: boolean +segment: + description: | + A ``segment`` object. + in: body + required: true + type: object +segment_description: + type: string + in: body + required: false + description: | + A free form description of the segment. Limited to 255 characters + in length. +segment_id: + description: | + The Id of the segment. + in: body + required: true + type: string +segment_name: + description: | + The segment name. + in: body + required: true + type: string +segment_recovery_method: + type: string + in: body + required: true + description: | + Type of recovery if any host in this segment goes down. User can mention + either 'AUTO', 'RESERVED_HOST', 'AUTO_PRIORITY' or 'RH_PRIORITY'. +segment_service_type: + type: string + in: body + required: true + description: | + The name of service which will be deployed in this segment. As of now + user can mention 'COMPUTE' as service_type. +segment_uuid: + description: | + The UUID of the segment. + in: body + required: true + type: string +segments: + description: | + A list of ``segment`` objects. + in: body + required: true + type: array +source_host_uuid: + description: | + The UUID of host for which notification is generated. + in: body + required: true + type: string +updated: + description: | + The date and time when the resource was updated. The date and time + stamp format is `ISO 8601 `_ + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2017-04-21T09:49:58-05:00``. The ``±hh:mm`` + value, if included, is the time zone as an offset from UTC. In + the previous example, the offset value is ``-05:00``. + in: body + required: true + type: string +version: + description: | + The version. + in: body + required: true + type: string +version_id: + type: string + in: body + required: true + description: > + A common name for the version in question. Informative only, it + has no real semantic meaning. +version_max: + type: string + in: body + required: true + description: > + The maximum version supported by API. +version_min: + type: string + in: body + required: true + description: > + The minimum version supported by API. +version_status: + type: string + in: body + required: true + description: | + The status of this API version. This can be one of: + + - ``CURRENT``: this is the preferred version of the API to use + - ``SUPPORTED``: this is an older, but still supported version of the API + - ``DEPRECATED``: a deprecated version of the API that is slated for removal +versions: + type: array + in: body + required: true + description: > + A list of version objects that describe the API versions available. diff --git a/api-ref/source/status.yaml b/api-ref/source/status.yaml new file mode 100644 index 00000000..496e4d9e --- /dev/null +++ b/api-ref/source/status.yaml @@ -0,0 +1,62 @@ +################# +# Success Codes # +################# +200: + default: | + Request was successful. +201: + default: | + Resource was created and is ready to use. +202: + default: | + Request was accepted for processing, but the processing has not been + completed. A 'location' header is included in the response which contains + a link to check the progress of the request. +204: + default: | + The server has fulfilled the request by deleting the resource. +300: + default: | + There are multiple choices for resources. The request has to be more + specific to successfully retrieve one of these resources. +302: + default: | + The response is about a redirection hint. The header of the response + usually contains a 'location' value where requesters can check to track + the real location of the resource. + +################# +# Error Codes # +################# + +400: + default: | + Some content in the request was invalid. + resource_signal: | + The target resource doesn't support receiving a signal. +401: + default: | + User must authenticate before making a request. +403: + default: | + Policy does not allow current user to do this operation. +404: + default: | + The requested resource could not be found. +405: + default: | + Method is not valid for this endpoint. +409: + default: | + This operation conflicted with another operation on this resource. + duplicate_zone: | + There is already a zone with this name. +500: + default: | + Something went wrong inside the service. This should not happen usually. + If it does happen, it means the server has experienced some serious + problems. +503: + default: | + Service is not available. This is mostly caused by service configuration + errors which prevents the service from successful start up. \ No newline at end of file diff --git a/api-ref/source/versions.inc b/api-ref/source/versions.inc new file mode 100644 index 00000000..658a496d --- /dev/null +++ b/api-ref/source/versions.inc @@ -0,0 +1,106 @@ +.. -*- rst -*- + +============== + API Versions +============== + +In order to bring new features to users over time, the Masakari API +supports versioning. + +- ''major versions'', which have dedicated urls + +The Version APIs work differently from other APIs as they *do not* +require authentication. + +List All Major 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 API version. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - versions: versions + - id: version_id + - status: version_status + - links: links + - version: version_max + - min_version: version_min + +.. note:: + + The ``updated`` parameter in the response is vestigial and provides + no useful information. + +Response Example +---------------- + +This demonstrates the expected response from a bleeding edge server +that supports up to the current version. + +.. literalinclude:: /../../doc/api_samples/versions/versions-get-resp.json + :language: javascript + + +Show Details of Specific API Version +==================================== + +.. rest_method:: GET /{api_version}/ + +This gets the details of a specific API at its root. Nearly all this +information exists at the API root, so this is mostly a redundant +operation. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - api_version: api_version + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - version: version + - id: version_id + - status: version_status + - links: links + - version: version_max + - min_version: version_min + +.. note:: + + The ``updated`` and ``media-types`` parameters in the response are + vestigial and provide no useful information. They will probably be + deprecated and removed in the future. + + +Response Example +---------------- + +This is an example of a ``GET /v1/`` on a relatively current server. + +.. literalinclude:: /../../doc/api_samples/versions/v1-version-get-resp.json + :language: javascript \ No newline at end of file diff --git a/doc/api_samples/hosts/host-create-req.json b/doc/api_samples/hosts/host-create-req.json new file mode 100644 index 00000000..3a7654ee --- /dev/null +++ b/doc/api_samples/hosts/host-create-req.json @@ -0,0 +1,7 @@ +{ + "host": { + "control_attributes": "SSH", + "type": "COMPUTE", + "name": "openstack-VirtualBox" + } +} diff --git a/doc/api_samples/hosts/host-create-resp.json b/doc/api_samples/hosts/host-create-resp.json new file mode 100644 index 00000000..7a77a170 --- /dev/null +++ b/doc/api_samples/hosts/host-create-resp.json @@ -0,0 +1,28 @@ +{ + "hosts": { + "reserved": false, + "uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "on_maintenance": false, + "created_at": "2017-04-21T10:09:20.000000", + "control_attributes": "SSH", + "updated_at": null, + "name": "openstack-VirtualBox", + "failover_segment": { + "uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b", + "deleted": false, + "created_at": "2017-04-20T10:17:17.000000", + "description": null, + "recovery_method": "auto", + "updated_at": null, + "service_type": "COMPUTE", + "deleted_at": null, + "id": 2, + "name": "segment2" + }, + "deleted_at": null, + "type": "COMPUTE_HOST", + "id": 1, + "failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b" + } +} \ No newline at end of file diff --git a/doc/api_samples/hosts/host-get-resp.json b/doc/api_samples/hosts/host-get-resp.json new file mode 100644 index 00000000..7a77a170 --- /dev/null +++ b/doc/api_samples/hosts/host-get-resp.json @@ -0,0 +1,28 @@ +{ + "hosts": { + "reserved": false, + "uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "on_maintenance": false, + "created_at": "2017-04-21T10:09:20.000000", + "control_attributes": "SSH", + "updated_at": null, + "name": "openstack-VirtualBox", + "failover_segment": { + "uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b", + "deleted": false, + "created_at": "2017-04-20T10:17:17.000000", + "description": null, + "recovery_method": "auto", + "updated_at": null, + "service_type": "COMPUTE", + "deleted_at": null, + "id": 2, + "name": "segment2" + }, + "deleted_at": null, + "type": "COMPUTE_HOST", + "id": 1, + "failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b" + } +} \ No newline at end of file diff --git a/doc/api_samples/hosts/host-update-req.json b/doc/api_samples/hosts/host-update-req.json new file mode 100644 index 00000000..304bbf9b --- /dev/null +++ b/doc/api_samples/hosts/host-update-req.json @@ -0,0 +1,5 @@ +{ + "host": { + "reserved": "True" + } +} diff --git a/doc/api_samples/hosts/host-update-resp.json b/doc/api_samples/hosts/host-update-resp.json new file mode 100644 index 00000000..7704bff8 --- /dev/null +++ b/doc/api_samples/hosts/host-update-resp.json @@ -0,0 +1,28 @@ +{ + "host": { + "reserved": true, + "uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "on_maintenance": false, + "created_at": "2017-04-21T10:09:20.000000", + "control_attributes": "SSH", + "updated_at": "2017-04-21T11:12:43.351320", + "name": "openstack-VirtualBox", + "failover_segment": { + "uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b", + "deleted": false, + "created_at": "2017-04-20T10:17:17.000000", + "description": null, + "recovery_method": "auto", + "updated_at": null, + "service_type": "Compute", + "deleted_at": null, + "id": 2, + "name": "new_segment" + }, + "deleted_at": null, + "type": "COMPUTE", + "id": 1, + "failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b" + } +} diff --git a/doc/api_samples/hosts/hosts-list-resp.json b/doc/api_samples/hosts/hosts-list-resp.json new file mode 100644 index 00000000..8ed074a1 --- /dev/null +++ b/doc/api_samples/hosts/hosts-list-resp.json @@ -0,0 +1,30 @@ +{ + "hosts": [ + { + "reserved": false, + "uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "on_maintenance": false, + "created_at": "2017-04-21T10:09:20.000000", + "control_attributes": "SSH", + "updated_at": null, + "name": "openstack-VirtualBox", + "failover_segment": { + "uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b", + "deleted": false, + "created_at": "2017-04-20T10:17:17.000000", + "description": null, + "recovery_method": "auto", + "updated_at": null, + "service_type": "COMPUTE", + "deleted_at": null, + "id": 2, + "name": "segment2" + }, + "deleted_at": null, + "type": "COMPUTE_HOST", + "id": 1, + "failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b" + } + ] +} \ No newline at end of file diff --git a/doc/api_samples/notifications/host-notification-create-req.json b/doc/api_samples/notifications/host-notification-create-req.json new file mode 100644 index 00000000..6ff789bf --- /dev/null +++ b/doc/api_samples/notifications/host-notification-create-req.json @@ -0,0 +1,12 @@ +{ + "notification": { + "type": "COMPUTE_HOST", + "generated_time": "2017-04-24 08:34:46", + "payload": { + "event": "STOPPED", + "host_status": "UNKNOWN", + "cluster_status": "OFFLINE" + }, + "hostname": "openstack-VirtualBox" + } +} diff --git a/doc/api_samples/notifications/host-notification-create-resp.json b/doc/api_samples/notifications/host-notification-create-resp.json new file mode 100644 index 00000000..f8eb18f8 --- /dev/null +++ b/doc/api_samples/notifications/host-notification-create-resp.json @@ -0,0 +1,19 @@ +{ + "notification": { + "notification_uuid": "9e66b95d-45da-4695-bfb6-ace68b35d955", + "status": "new", + "source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "created_at": "2017-04-24T06:37:37.396994", + "updated_at": null, + "id": 4, + "generated_time": "2017-04-24T08:34:46.000000", + "deleted_at": null, + "type": "COMPUTE_HOST", + "payload": { + "host_status": "UNKNOWN", + "event": "STOPPED", + "cluster_status": "OFFLINE" + } + } +} diff --git a/doc/api_samples/notifications/notifcations-list-resp.json b/doc/api_samples/notifications/notifcations-list-resp.json new file mode 100644 index 00000000..018b09a1 --- /dev/null +++ b/doc/api_samples/notifications/notifcations-list-resp.json @@ -0,0 +1,20 @@ +{ + "notifications": [ + { + "notification_uuid": "32bc95ac-858d-460a-b562-7e365391be64", + "status": "new", + "source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "created_at": "2017-04-21T12:09:44.000000", + "updated_at": null, + "id": 1, + "generated_time": "2017-04-21T17:29:55.000000", + "deleted_at": null, + "type": "PROCESS", + "payload": { + "process_name": "nova-compute", + "event": "stopped" + } + } + ] +} diff --git a/doc/api_samples/notifications/notification-get-resp.json b/doc/api_samples/notifications/notification-get-resp.json new file mode 100644 index 00000000..f8eb18f8 --- /dev/null +++ b/doc/api_samples/notifications/notification-get-resp.json @@ -0,0 +1,19 @@ +{ + "notification": { + "notification_uuid": "9e66b95d-45da-4695-bfb6-ace68b35d955", + "status": "new", + "source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "created_at": "2017-04-24T06:37:37.396994", + "updated_at": null, + "id": 4, + "generated_time": "2017-04-24T08:34:46.000000", + "deleted_at": null, + "type": "COMPUTE_HOST", + "payload": { + "host_status": "UNKNOWN", + "event": "STOPPED", + "cluster_status": "OFFLINE" + } + } +} diff --git a/doc/api_samples/notifications/process-notification-create-req.json b/doc/api_samples/notifications/process-notification-create-req.json new file mode 100644 index 00000000..406b9a89 --- /dev/null +++ b/doc/api_samples/notifications/process-notification-create-req.json @@ -0,0 +1,11 @@ +{ + "notification": { + "type": "PROCESS", + "generated_time": "2017-04-21 17:29:55", + "payload": { + "process_name": "nova-compute", + "event": "stopped" + }, + "hostname": "openstack-VirtualBox" + } +} diff --git a/doc/api_samples/notifications/process-notification-create-resp.json b/doc/api_samples/notifications/process-notification-create-resp.json new file mode 100644 index 00000000..9953749a --- /dev/null +++ b/doc/api_samples/notifications/process-notification-create-resp.json @@ -0,0 +1,18 @@ +{ + "notification": { + "notification_uuid": "2b412acf-c55a-442d-8fd2-e823ec0d827f", + "status": "new", + "source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "created_at": "2017-04-24T06:05:29.387678", + "updated_at": null, + "id": 2, + "generated_time": "2017-04-21T17:29:55.000000", + "deleted_at": null, + "type": "PROCESS", + "payload": { + "process_name": "nova-compute", + "event": "stopped" + } + } +} diff --git a/doc/api_samples/notifications/vm-notification-create-req.json b/doc/api_samples/notifications/vm-notification-create-req.json new file mode 100644 index 00000000..2539870b --- /dev/null +++ b/doc/api_samples/notifications/vm-notification-create-req.json @@ -0,0 +1,12 @@ +{ + "notification": { + "type": "VM", + "generated_time": "2017-04-23T07:18:51.523726", + "payload": { + "instance_uuid": "96ab1c42-668c-4f2d-8689-afa3301d4ee9", + "vir_domain_event": "STOPPED_DESTROYED", + "event": "LIFECYCLE" + }, + "hostname": "openstack-VirtualBox" + } +} diff --git a/doc/api_samples/notifications/vm-notification-create-resp.json b/doc/api_samples/notifications/vm-notification-create-resp.json new file mode 100644 index 00000000..114399b2 --- /dev/null +++ b/doc/api_samples/notifications/vm-notification-create-resp.json @@ -0,0 +1,19 @@ +{ + "notification": { + "notification_uuid": "f4836386-7648-4395-89b6-75a2c5ca7ff2", + "status": "new", + "source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd", + "deleted": false, + "created_at": "2017-04-24T06:22:47.569979", + "updated_at": null, + "id": 3, + "generated_time": "2017-04-23T07:18:51.523726", + "deleted_at": null, + "type": "VM", + "payload": { + "instance_uuid": "96ab1c42-668c-4f2d-8689-afa3301d4ee9", + "vir_domain_event": "STOPPED_DESTROYED", + "event": "LIFECYCLE" + } + } +} diff --git a/doc/api_samples/segments/segment-create-req.json b/doc/api_samples/segments/segment-create-req.json new file mode 100644 index 00000000..fdb00bd2 --- /dev/null +++ b/doc/api_samples/segments/segment-create-req.json @@ -0,0 +1,7 @@ +{ + "segment" : { + "service_type": "COMPUTE", + "recovery_method": "AUTO", + "name": "new_segment" + } +} \ No newline at end of file diff --git a/doc/api_samples/segments/segment-create-resp.json b/doc/api_samples/segments/segment-create-resp.json new file mode 100644 index 00000000..c4ecc571 --- /dev/null +++ b/doc/api_samples/segments/segment-create-resp.json @@ -0,0 +1,14 @@ +{ + "segment": { + "uuid": "5fd9f925-0379-40db-a7f8-786a0b655b2a", + "deleted": false, + "created_at": "2017-04-21T08:59:53.991030", + "description": null, + "recovery_method": "AUTO", + "updated_at": null, + "service_type": "COMPUTE", + "deleted_at": null, + "id": 4, + "name": "new_segment" + } +} diff --git a/doc/api_samples/segments/segment-get-resp.json b/doc/api_samples/segments/segment-get-resp.json new file mode 100644 index 00000000..c4ecc571 --- /dev/null +++ b/doc/api_samples/segments/segment-get-resp.json @@ -0,0 +1,14 @@ +{ + "segment": { + "uuid": "5fd9f925-0379-40db-a7f8-786a0b655b2a", + "deleted": false, + "created_at": "2017-04-21T08:59:53.991030", + "description": null, + "recovery_method": "AUTO", + "updated_at": null, + "service_type": "COMPUTE", + "deleted_at": null, + "id": 4, + "name": "new_segment" + } +} diff --git a/doc/api_samples/segments/segment-update-req.json b/doc/api_samples/segments/segment-update-req.json new file mode 100644 index 00000000..a2cc583a --- /dev/null +++ b/doc/api_samples/segments/segment-update-req.json @@ -0,0 +1,5 @@ +{ + "segment": { + "name": "new_segment" + } +} diff --git a/doc/api_samples/segments/segment-update-resp.json b/doc/api_samples/segments/segment-update-resp.json new file mode 100644 index 00000000..ec07376d --- /dev/null +++ b/doc/api_samples/segments/segment-update-resp.json @@ -0,0 +1,14 @@ +{ + "segment": { + "uuid": "5fd9f925-0379-40db-a7f8-786a0b655b2a", + "deleted": false, + "created_at": "2017-04-21T08:59:54.000000", + "description": null, + "recovery_method": "AUTO", + "updated_at": "2017-04-21T09:47:03.748028", + "service_type": "COMPUTE", + "deleted_at": null, + "id": 4, + "name": "new_segment" + } +} diff --git a/doc/api_samples/segments/segments-list-resp.json b/doc/api_samples/segments/segments-list-resp.json new file mode 100644 index 00000000..63f33943 --- /dev/null +++ b/doc/api_samples/segments/segments-list-resp.json @@ -0,0 +1,16 @@ +{ + "segments": [ + { + "uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b", + "deleted": false, + "created_at": "2017-04-20T10:17:17.000000", + "description": "Segment1", + "recovery_method": "auto", + "updated_at": null, + "service_type": "Compute", + "deleted_at": null, + "id": 1, + "name": "segment2" + } + ] +} \ No newline at end of file diff --git a/doc/api_samples/versions/v1-version-get-resp.json b/doc/api_samples/versions/v1-version-get-resp.json new file mode 100644 index 00000000..92d0d3a8 --- /dev/null +++ b/doc/api_samples/versions/v1-version-get-resp.json @@ -0,0 +1,26 @@ +{ + "version": { + "id": "v1", + "links": [ + { + "href": "http://openstack.example.com/v1/", + "rel": "self" + }, + { + "href": "http://docs.openstack.org/", + "rel": "describedby", + "type": "text/html" + } + ], + "media-types": [ + { + "base": "application/json", + "type": "application/vnd.openstack.masakari+json;version=1" + } + ], + "status": "CURRENT", + "version": "1.0", + "min_version": "1.0", + "updated": "2016-07-01T11:33:21Z" + } +} \ No newline at end of file diff --git a/doc/api_samples/versions/versions-get-resp.json b/doc/api_samples/versions/versions-get-resp.json new file mode 100644 index 00000000..22c0a935 --- /dev/null +++ b/doc/api_samples/versions/versions-get-resp.json @@ -0,0 +1,17 @@ +{ + "versions": [ + { + "id": "v1.0", + "links": [ + { + "href": "http://openstack.example.com/v1/", + "rel": "self" + } + ], + "status": "CURRENT", + "version": "1.0", + "min_version": "1.0", + "updated": "2016-07-01T11:33:21Z" + } + ] +} \ No newline at end of file diff --git a/test-requirements.txt b/test-requirements.txt index 8318d578..18aba839 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -10,6 +10,8 @@ psycopg2>=2.6.2 # LGPL/ZPL PyMySQL>=0.7.6 # MIT License python-subunit>=0.0.18 # Apache-2.0/BSD sphinx>=1.6.2 # BSD +openstackdocstheme>=1.17.0 # Apache-2.0 +os-api-ref>=1.4.0 # Apache-2.0 oslosphinx>=4.7.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 os-testr>=1.0.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 8cde388f..32f2da49 100644 --- a/tox.ini +++ b/tox.ini @@ -57,6 +57,13 @@ commands = [testenv:debug] commands = oslo_debug_helper {posargs} +[testenv:api-ref] +# This environment is called from CI scripts to test and publish +# the API Ref to developer.openstack.org. +commands = + rm -rf api-ref/build + sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html + [flake8] # E123, E125 skipped as they are invalid PEP-8.