Updated freezer-api api-ref documentation

* Update api-ref structure * Added v2 * Backup list * Job list * Job Create Implements blueprint implement-api-ref-doc Change-Id: I643ca44565331ef9d0fc36189d60489523e3235e
6 years ago · 69719590b7
parent aaf25116e4
commit 69719590b7
52 changed files with 2393 additions and 57 deletions
--- a/api-ref/source/conf.py
+++ b/api-ref/source/conf.py
@ -1,32 +1,34 @@
-"""
-(c) Copyright 2016 Hewlett-Packard Enterprise Development Company, L.P.
-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.
-
-"""
+# -*- coding: utf-8 -*-
+#
+# 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.
+#
+# freezer api-ref build config file, copied from:
+# nova documentation build configuration file, created by
+# sphinx-quickstart on Sat May  1 15:17:47 2010.
+#
+# This file is executed 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
-
-# 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.
+import warnings

 import openstackdocstheme

@ -34,12 +36,25 @@ extensions = [
    'os_api_ref',
 ]

+
 html_theme = 'openstackdocs'
 html_theme_path = [openstackdocstheme.get_html_theme_path()]
 html_theme_options = {
    "sidebar_mode": "toc",
 }

+# 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'

@ -57,7 +72,7 @@ copyright = u'2010-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 freezer_api import version_info
 # The full version, including alpha/beta/rc tags.
 release = version_info.release_string()
@ -147,10 +162,15 @@ html_context = {'bug_tag': 'api-ref',
 # 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"]
-html_last_updated_fmt = subprocess.Popen(
-    git_cmd, stdout=subprocess.PIPE).communicate()[0]
+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]
+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.
@ -184,7 +204,7 @@ html_last_updated_fmt = subprocess.Popen(
 # html_file_suffix = ''

 # Output file base name for HTML help builder.
-htmlhelp_basename = 'freezerdoc'
+htmlhelp_basename = 'freezerapidoc'


 # -- Options for LaTeX output -------------------------------------------------
@ -199,9 +219,9 @@ htmlhelp_basename = 'freezerdoc'
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
-    ('index', 'Freezer.tex', u'OpenStack Backup and Disaster Recovery Service '
-                             u'API Documentation', u'OpenStack Foundation',
-     'manual'),
+    ('index', 'Freezerapi.tex', u'OpenStack Backup and Disaster Recovery '
+                                u'Service API Documentation',
+     u'OpenStack Foundation', 'manual'),
 ]

 # The name of an image file (relative to this directory) to place at the top of
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@ -1,20 +1,26 @@
 ..
-      (c) Copyright 2016 Hewlett-Packard Enterprise Development Company, L.P.
-      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.
+      Copyright 2010 OpenStack Foundation
+      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

-:tocdepth: 2
+          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.

 ==========================
 Backup and DR Service APIs
 ==========================

-.. include:: versions.inc
+.. toctree::
+   :maxdepth: 2
+
+   versions/index
+   v1/index
+   v2/index
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@ -1,8 +0,0 @@
-###############################  Response  ####################################
-
-versions:
-  type: list
-  in: body
-  required: True
-  description: |
-    A list of supported major API versions.
--- a/api-ref/source/v1/actions-v1.inc
+++ b/api-ref/source/v1/actions-v1.inc
@ -0,0 +1,225 @@
+=================
+Actions (actions)
+=================
+
+Actions allow users to execute backups and restore operations on one node
+or more. Actions are stored through the api in the database. It is included
+in the job, every job contains set of actions that carry out the backup/restore
+job.
+
+Lists Actions
+=============
+
+.. rest_method::  GET /v1/actions
+
+Lists actions.
+
+This operation lists actions.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - offset: marker
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - actions: actions
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/actions-list-response.json
+   :language: javascript
+
+
+Creates action
+==============
+
+.. rest_method:: POST /v1/actions
+
+Creates an action.
+
+This operation creates a new action.
+
+The ``body`` attribute specifies contains a set of actions that gets created
+ one the job is submitted.
+
+The ``description`` is the name that you give to the job. The name must not
+exceed 64 bytes in length.
+
+The ``job_schedule`` is very important to schedule the job or it will run only
+once. also you can provide ``event`` which can automatically start/stop the
+job.
+
+The ``freezer_action`` holds the actual action parameters. ``freezer_action``
+differs from action to another as it depends what this action is doing (backup,
+restore, admin, info)
+
+Normal response codes: 201
+
+Error response codes:
+
+- Syntax Error (753)
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - freezer_action: freezer_action
+  - max_retries: max_retries
+  - max_retries_interval: max_retries_interval
+
+Request Example
+---------------
+
+.. literalinclude:: samples/actions-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - action_id: action_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/actions-create-response.json
+   :language: javascript
+
+
+
+Show actions
+============
+
+.. rest_method::  GET /v1/actions/{action_id}
+
+Shows actions.
+
+This operation shows a certain action. The action details.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - action_id: action_id_path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - freezer_action: freezer_action
+  - max_retries: max_retries
+  - max_retries_interval: max_retries_interval
+  - user_id: user_id
+  - action_id: action_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/actions-get-response.json
+   :language: javascript
+
+
+Updates actions
+===============
+
+.. rest_method:: POST /v1/actions/{action_id}
+
+Updates an action.
+
+This operation updates or replaces an existing action.
+
+Normal response codes: 201
+
+Error response codes:
+
+- Syntax Error (753)
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - action_id: action_id_path
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - freezer_action: freezer_action
+  - max_retries: max_retries
+  - max_retries_interval: max_retries_interval
+  - action_id: action_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/actions-update-request.json
+   :language: javascript
+
+Response Example
+----------------
+
+.. literalinclude:: samples/actions-update-response.json
+   :language: javascript
+
+
+Delete actions
+==============
+
+.. rest_method::  DELETE /v1/actions/{action_id}
+
+Delete actions.
+
+This operation deletes a certain action.
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - action_id: action_id_path
+
+There is no response for this operation.
--- a/api-ref/source/v1/backups-v1.inc
+++ b/api-ref/source/v1/backups-v1.inc
@ -0,0 +1,111 @@
+=================
+Backups (backups)
+=================
+
+Backups allow users to record their backups and metadata information about
+those backups and when backups were taken. It holds the backup information.
+
+Lists backups
+=============
+
+.. rest_method::  GET /v1/backups
+
+Lists backups.
+
+This operation lists backups for the project.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - offset: marker
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - backups: backups
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/backup-list-response.json
+   :language: javascript
+
+
+Show backups
+============
+
+.. rest_method::  GET /v1/backups/{backup_id}
+
+Show backups.
+
+This operation shows a certain backup . It displays all backup details.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - backup_id: backup_id_path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - user_id: user_id
+  - backup_id: backup_id
+  - user_name: username
+  - backup_metadata: backup_metadata
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/backup-get-response.json
+   :language: javascript
+
+
+Delete backups
+==============
+
+.. rest_method::  DELETE /v1/backups/{backup_id}
+
+Delete backups.
+
+This operation deletes a certain backup .
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - backup_id: backup_id_path
+
+There is no response for this operation.
--- a/api-ref/source/v1/clients-v1.inc
+++ b/api-ref/source/v1/clients-v1.inc
@ -0,0 +1,161 @@
+=================
+Clients (clients)
+=================
+
+Clients allow freezer schedulers or users to create a client to be able to
+create, update, show or delete job. The client is required to record you
+backups on freezer api.
+
+Lists clients
+=============
+
+.. rest_method::  GET /v1/clients
+
+Lists clients.
+
+This operation lists clients.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - offset: marker
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - clients: clients
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/clients-list-response.json
+   :language: javascript
+
+
+Creates Client
+==============
+
+.. rest_method:: POST /v1/clients
+
+Creates a client.
+
+This operation creates a new client.
+
+Normal response codes: 201
+
+Error response codes:
+
+- Syntax Error (753)
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - hostname: hostname
+  - uuid: uuid
+  - client_id: client_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/clients-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - client_id: client_id
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/clients-create-response.json
+   :language: javascript
+
+
+Show clients
+============
+
+.. rest_method::  GET /v1/clients/{client_id}
+
+Show clients.
+
+This operation shows a certain client . It displays all client details.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - client_id: client_id_path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - user_id: user_id
+  - client_id: client_id
+  - hostname: hostname
+  - uuid: uuid
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/client-get-response.json
+   :language: javascript
+
+
+Delete clients
+==============
+
+.. rest_method::  DELETE /v1/clients/{client_id}
+
+Delete clients.
+
+This operation deletes a certain client.
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - client_id: client_id_path
+
+There is no response for this operation.
--- a/api-ref/source/v1/index.rst
+++ b/api-ref/source/v1/index.rst
@ -0,0 +1,29 @@
+..
+      Copyright 2010 OpenStack Foundation
+      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.
+
+:tocdepth: 3
+
+===============================
+Backup Service API v1 (CURRENT)
+===============================
+
+.. rest_expand_all::
+
+.. include:: backups-v1.inc
+.. include:: jobs-v1.inc
+.. include:: clients-v1.inc
+.. include:: actions-v1.inc
+.. include:: sessions-v1.inc
--- a/api-ref/source/v1/jobs-v1.inc
+++ b/api-ref/source/v1/jobs-v1.inc
@ -0,0 +1,226 @@
+=================
+Jobs (jobs)
+=================
+
+Jobs allow users to schedule and execute backup jobs on one node or more. Jobs
+ are stored through the api in the database. Every job contains set of actions
+  that carry out the backup job.
+
+Lists jobs
+==========
+
+.. rest_method::  GET /v1/jobs
+
+Lists jobs.
+
+This operation lists jobs for the project.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - offset: marker
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - jobs: jobs
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/jobs-list-response.json
+   :language: javascript
+
+
+Creates job
+===========
+
+.. rest_method:: POST /v1/jobs
+
+Creates a job.
+
+This operation creates a new job.
+
+The ``body`` attribute specifies contains a set of actions that gets created
+ one the job is submitted.
+
+The ``description`` is the name that you give to the job. The name must not
+exceed 64 bytes in length.
+
+The ``job_schedule`` is very important to schedule the job or it will run only
+once. also you can provide ``event`` which can automatically start/stop the
+job.
+
+The ``job_actions`` the actual backup or restore action to be done.
+
+Normal response codes: 201
+
+Error response codes:
+
+- Syntax Error (753)
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - description: job_description_req
+  - job_schedule: job_schedule_req
+  - job_actions: job_actions_req
+
+Request Example
+---------------
+
+.. literalinclude:: samples/job-create-request.json
+   :language: javascript
+
+
+This operation does not return a response body.
+
+
+Show jobs
+=========
+
+.. rest_method::  GET /v1/jobs/{job_id}
+
+Shows jobs.
+
+This operation shows a certain job. It displays all job details with actions
+inside the job.
+
+
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - job_id: job_id_path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - user_id: user_id
+  - description: job_description_req
+  - job_schedule: job_schedule_req
+  - client_id: client_id
+  - job_actions: job_actions_req
+  - job_id: job_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/job-get-response.json
+   :language: javascript
+
+
+Updates jobs
+============
+
+.. rest_method:: PATCH /v1/jobs/{job_id}
+
+Updates a job.
+
+This operation creates a new job.
+
+The ``body`` attribute specifies contains a set of actions that gets updated
+ once the job is submitted.
+
+The ``description`` is the name that you give to the job. The name should not
+exceed 64 bytes in length.
+
+The ``job_schedule`` is very important to schedule the job or it will run only
+once. also you can provide ``event`` which can automatically start/stop the
+job.
+
+The ``job_actions`` the actual backup or restore action to be done.
+
+Normal response codes: 201
+
+Error response codes:
+
+- Syntax Error (753)
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - job_id: job_id_path
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - description: job_description_req
+  - job_schedule: job_schedule_req
+  - job_actions: job_actions_req
+
+Request Example
+---------------
+
+.. literalinclude:: samples/job-update-request.json
+   :language: javascript
+
+Response Example
+----------------
+
+.. literalinclude:: samples/job-update-response.json
+   :language: javascript
+
+
+Delete jobs
+===========
+
+.. rest_method::  DELETE /v1/jobs/{job_id}
+
+Delete jobs.
+
+This operation deletes a certain job .
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - job_id: job_id_path
+
+There is no response for this operation.
--- a/api-ref/source/v1/parameters.yaml
+++ b/api-ref/source/v1/parameters.yaml
@ -0,0 +1,272 @@
+###############################  Query  ####################################
+
+action_id_path:
+  type: string
+  in: query
+  required: true
+  description: |
+    The action UUID.
+
+backup_id_path:
+  type: string
+  in: query
+  required: true
+  description: |
+    The UUID of the backup.
+
+client_id_path:
+  type: string
+  in: query
+  required: true
+  description: |
+    The client ID.
+
+job_id_path:
+  type: string
+  in: query
+  required: true
+  description: |
+    The job UUID.
+
+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
+
+session_id_path:
+  type: string
+  in: query
+  required: true
+  description: |
+    The session UUID.
+
+###############################  Body  ####################################
+
+action_id:
+  type: string
+  in: body
+  required: true
+  description: |
+    The action UUID.
+
+actions:
+  type: list
+  in: body
+  required: true
+  description: |
+    A list of actions.
+
+backup_id:
+  type: string
+  in: body
+  required: true
+  description: |
+    The UUID of the backup.
+
+backup_metadata:
+  type: list
+  in: body
+  required: true
+  description: |
+    A list of backup metada information. This contains the backup details.
+    like ``path_to_backup``, ``backup_name``, ``hostname``, ``job_id``,
+    ``storage``, ...
+
+backups:
+  type: list
+  in: body
+  description: |
+    A list of backups.
+
+client_id:
+  type: string
+  in: body
+  required: true
+  description: |
+    The client UUID.
+
+clients:
+  type: list
+  in: body
+  required: true
+  description: |
+    A list of clients.
+
+freezer_action:
+  type: dict
+  in: body
+  required: true
+  description: |
+    Action parameters. It depends on the actual action (backup, restore,
+    admin, info) so the parameters differ.
+
+hostname:
+  type: string
+  in: body
+  required: true
+  description: |
+    The hostname of the machine that client is running on.
+
+job_actions_req:
+  type: list
+  in: body
+  required: true
+  description: |
+    A list of actions that carry out the backup/restore job.
+
+job_description_req:
+  type: string
+  in: body
+  required: true
+  description: |
+    The name of the job.
+
+job_id:
+  type: string
+  in: body
+  required: true
+  description: |
+    The job UUID.
+
+job_schedule_req:
+  type: dict
+  in: body
+  required: true
+  description: |
+    The schedule information of the job.
+
+jobs:
+  type: list
+  in: body
+  description: |
+    A list of jobs.
+
+max_retries:
+  type: int
+  in: body
+  description: |
+    A number of times freezer should retry to execute the action.
+
+max_retries_interval:
+  type: int
+  in: body
+  description: |
+    The time that freezer should wait between diferrent retrials to execute
+    the action.
+
+result:
+  type: string
+  in: body
+  description: |
+    A string represents if the operation was successful ``success`` or failed.
+
+session_description:
+  type: string
+  in: body
+  required: true
+  description: |
+    A description of the session.
+
+session_event:
+  type: string
+  in: body
+  description: |
+    The event is being used to start or stop a session.
+
+session_hold_off:
+  type: int
+  in: body
+  required: true
+  description: |
+    Amount of time to wait before re-running the same session again.
+
+session_id:
+  type: string
+  in: body
+  required: true
+  description: |
+    The session UUID.
+
+session_schedule:
+  type: dict
+  in: body
+  required: true
+  description: |
+    A dictionary that holds the session secheduling information. It's the
+    same like job_schedule. it contains ``schedule_interval``, ``status``
+    and ``event``.
+
+session_schedule_internval:
+  type: string
+  in: body
+  description: |
+    The scheduling information of the session. for examples "2 hours" it
+    means the session will be executed every 2 hours.
+
+session_status:
+  type: string
+  in: body
+  description: |
+    The status of the session. Default is ``active``.
+
+session_tag:
+  type: string
+  in: body
+  required: true
+  description: |
+    The event is being used to start or stop a session.
+
+sessions:
+  type: list
+  in: body
+  description: |
+    A list of existing sessions.
+
+user_id:
+  type: string
+  in: body
+  required: true
+  description: |
+    The user UUID.
+
+username:
+  type: string
+  in: body
+  required: true
+  description: |
+    The username.
+
+uuid:
+  type: string
+  in: body
+  required: true
+  description: |
+    The client UUID.
+
+version_doc:
+  type: int
+  in: body
+  required: true
+  description: |
+    The document version.
+
+versions:
+  type: list
+  in: body
+  required: True
+  description: |
+    A list of supported major API versions.
--- a/api-ref/source/v1/samples/actions-create-request.json
+++ b/api-ref/source/v1/samples/actions-create-request.json
@ -0,0 +1,15 @@
+{
+            "freezer_action":
+            {
+                "backup_name": "production_backup",
+                "container": "prod_container",
+                "no_incremental": true,
+                "path_to_backup": "/etc/",
+                "snapshot": true,
+                "action": "backup",
+                "remove_older_than": 365,
+                "log_file": "/var/log/freezer/job0001.log"
+            },
+            "max_retries": 5,
+            "max_retries_interval": 6
+}
--- a/api-ref/source/v1/samples/actions-create-response.json
+++ b/api-ref/source/v1/samples/actions-create-response.json
@ -0,0 +1,4 @@
+{
+        "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
+}
+
--- a/api-ref/source/v1/samples/actions-get-response.json
+++ b/api-ref/source/v1/samples/actions-get-response.json
@ -0,0 +1,18 @@
+{
+        "freezer_action":
+        {
+            "backup_name": "production_backup",
+            "container": "prod_container",
+            "no_incremental": true,
+            "path_to_backup": "/etc/",
+            "snapshot": true,
+            "action": "backup",
+            "remove_older_than": 365,
+            "log_file": "/var/log/freezer/job0001.log"
+        },
+        "max_retries_interval": 6,
+        "_version": 1,
+        "max_retries": 5,
+        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+        "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
+}
--- a/api-ref/source/v1/samples/actions-list-response.json
+++ b/api-ref/source/v1/samples/actions-list-response.json
@ -0,0 +1,42 @@
+{
+        "actions":
+        [
+            {
+                "freezer_action":
+                {
+                    "backup_name": "test0001_backup",
+                    "container": "test0001_container",
+                    "no_incremental": true,
+                    "path_to_backup": "/etc/",
+                    "project_id": "752d8bd43d654e7a840bbfda77ce41af",
+                    "snapshot": true,
+                    "action": "backup",
+                    "remove_older_than": 365,
+                    "log_file": "/home/saad/job0001.log"
+                },
+                "max_retries": 5,
+                "max_retries_interval": 6,
+                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+                "action_id": "061f7657350a4bddbfabf8d2a25dad96"
+            },
+            {
+                "freezer_action":
+                {
+                    "backup_name": "test0001_backup",
+                    "container": "/tmp/test0001_container",
+                    "no_incremental": true,
+                    "path_to_backup": "/etc/",
+                    "storage": "local",
+                    "project_id": "752d8bd43d654e7a840bbfda77ce41af",
+                    "snapshot": false,
+                    "action": "backup",
+                    "remove_older_than": 365,
+                    "log_file": "/home/saad/job0001.log"
+                },
+                "max_retries": 5,
+                "max_retries_interval": 6,
+                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+                "action_id": "317f8bc1fbbe49819d1b60f4b4387e63"
+            }
+        ]
+}
--- a/api-ref/source/v1/samples/actions-update-request.json
+++ b/api-ref/source/v1/samples/actions-update-request.json
@ -0,0 +1,15 @@
+{
+            "freezer_action":
+            {
+                "backup_name": "production_backup",
+                "container": "prod_container",
+                "no_incremental": true,
+                "path_to_backup": "/etc/",
+                "snapshot": true,
+                "action": "backup",
+                "remove_older_than": 365,
+                "log_file": "/var/log/freezer/job0001.log"
+            },
+            "max_retries": 5,
+            "max_retries_interval": 6
+}
--- a/api-ref/source/v1/samples/actions-update-response.json
+++ b/api-ref/source/v1/samples/actions-update-response.json
@ -0,0 +1,5 @@
+{
+  "version": 2,
+  "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
+}
+
--- a/api-ref/source/v1/samples/backup-get-response.json
+++ b/api-ref/source/v1/samples/backup-get-response.json
@ -0,0 +1,38 @@
+{
+        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+        "backup_id": "96a5946a6e994a38a3d1008fbc6f3406",
+        "user_name": "demo",
+        "backup_metadata":
+        {
+            "ssh_port": 22,
+            "consistency_checksum": "",
+            "curr_backup_level": 0,
+            "backup_name": "test0001_backup",
+            "container": "/tmp/test0001_container",
+            "compression": "gzip",
+            "dry_run": "",
+            "hostname": "szaher",
+            "storage": "local",
+            "vol_snap_path": "/etc/",
+            "os_auth_version": "",
+            "client_os": "linux2",
+            "time_stamp": 1493052022,
+            "container_segments": "",
+            "ssh_username": "",
+            "path_to_backup": "/etc/",
+            "ssh_key": "",
+            "proxy": "",
+            "job_id": "0ae284d514eb47dd84154748b5056749",
+            "always_level": "",
+            "max_level": "",
+            "backup_media": "fs",
+            "ssh_host": "",
+            "mode": "fs",
+            "fs_real_path": "/etc/",
+            "action": "backup",
+            "client_version": "5.0.0",
+            "log_file": "/home/saad/job0001.log"
+        },
+        "_version": 1
+}
+
--- a/api-ref/source/v1/samples/backup-list-response.json
+++ b/api-ref/source/v1/samples/backup-list-response.json
@ -0,0 +1,76 @@
+{
+  "backups": [
+    {
+      "backup_id": "96a5946a6e994a38a3d1008fbc6f3406",
+      "user_id": "a387de3311484ce58c4560486bc153f1",
+      "job_id": "df96800d16fc4d28af75c8451daf0a92",
+      "backup_metadata": {
+        "ssh_port": 22,
+        "curr_backup_level": 0,
+        "backup_name": "freezer_mysql_backup",
+        "container": "freezer_database_backups",
+        "compression": "gzip",
+        "dry_run": "",
+        "hostname": "backup-node1",
+        "storage": "swift",
+        "vol_snap_path": "\/var\/lib\/freezer_81856317d419498cb95f3bdffc847361\/.",
+        "os_auth_version": "",
+        "client_os": "linux2",
+        "time_stamp": 1486660214,
+        "container_segments": "",
+        "ssh_username": "",
+        "path_to_backup": "\/var\/lib\/freezer_81856317d419498cb95f3bdffc847361\/.",
+        "ssh_key": "",
+        "proxy": "",
+        "always_level": "",
+        "max_level": 14,
+        "backup_media": "fs",
+        "ssh_host": "",
+        "mode": "mysql",
+        "fs_real_path": "\/var\/lib\/mysql\/",
+        "action": "backup",
+        "client_version": "2.0.2",
+        "log_file": "\/root\/.freezer\/freezer.log"
+      },
+      "client_id": "backup-node1",
+      "backup_uuid": "9598dd99e1ce42019e498c5493ae1f84",
+      "user_name": "os_backup"
+    },
+    {
+      "backup_id": "0cd44caf6db5486b94a04b33256a5ff4",
+      "user_id": "a387de3311484ce58c4560486bc153f1",
+      "job_id": "b30efac3ef744c45bf3062775ea3525b",
+      "backup_metadata": {
+        "ssh_port": 22,
+        "curr_backup_level": 0,
+        "backup_name": "freezer_mysql_backup",
+        "container": "freezer_database_backups",
+        "compression": "gzip",
+        "dry_run": "",
+        "hostname": "backup-node1",
+        "storage": "swift",
+        "vol_snap_path": "\/var\/lib\/freezer_c5d4504387f84b1e96266b6f00bf5f04\/.",
+        "os_auth_version": "",
+        "client_os": "linux2",
+        "time_stamp": 1486660222,
+        "container_segments": "",
+        "ssh_username": "",
+        "path_to_backup": "\/var\/lib\/freezer_c5d4504387f84b1e96266b6f00bf5f04\/.",
+        "ssh_key": "",
+        "proxy": "",
+        "always_level": "",
+        "max_level": 14,
+        "backup_media": "fs",
+        "ssh_host": "",
+        "mode": "mysql",
+        "fs_real_path": "\/var\/lib\/mysql\/",
+        "action": "backup",
+        "client_version": "2.0.2",
+        "log_file": "\/root\/.freezer\/freezer.log"
+      },
+      "client_id": "backup-node1",
+      "backup_uuid": "2ba51cb9eff543d4b9a530b3c0d2f7cc",
+      "user_name": "os_backup"
+    }
+  ]
+}
--- a/api-ref/source/v1/samples/client-get-response.json
+++ b/api-ref/source/v1/samples/client-get-response.json
@ -0,0 +1,15 @@
+{
+        "client":
+        {
+            "client":
+            {
+                "hostname": "szaher01",
+                "uuid": "c4031a4885384376a717a238de975a9c"
+            },
+            "user_id": "5cd44cafcdb5386b94a04b33d56a5ff6",
+            "uuid": "6f588392aa864c96b4af96a4eae005ce",
+            "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher01"
+        },
+        "user_id": "0cd44caf6db5486b94a04b33256a5ff4"
+}
+
--- a/api-ref/source/v1/samples/clients-create-request.json
+++ b/api-ref/source/v1/samples/clients-create-request.json
@ -0,0 +1,8 @@
+{
+            "client":
+            {
+                "hostname": "szaher01",
+                "uuid": "c4031a4885384376a717a238de975a9c"
+            },
+            "client_id": "752d8cd43d654e7a840bbfd277ce41af_szaher01"
+}
--- a/api-ref/source/v1/samples/clients-create-response.json
+++ b/api-ref/source/v1/samples/clients-create-response.json
@ -0,0 +1 @@
+{"client_id": "752d8cd43d654e7a840bbfd277ce41af_szaher01"}
--- a/api-ref/source/v1/samples/clients-list-response.json
+++ b/api-ref/source/v1/samples/clients-list-response.json
@ -0,0 +1,28 @@
+{
+        "clients":
+        [
+            {
+                "client":
+                {
+                    "client":
+                    {
+                        "hostname": "szaher01",
+                        "uuid": "c4031a4885384376a717a238de975a9c"
+                    },
+                    "user_id": "5cd44cafcdb5386b94a04b33d56a5ff6",
+                    "uuid": "6f588392aa864c96b4af96a4eae005ce",
+                    "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher01"
+                },
+                "user_id": "0cd44caf6db5486b94a04b33256a5ff4"
+            },
+            {
+                "client":
+                {
+                    "hostname": "szaher",
+                    "uuid": "c4031a9885384376a717a238ae975d9b",
+                    "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher"
+                },
+                "user_id": "0cd44caf6db5486b94a04b33256a5ff4"
+            }
+        ]
+}
--- a/api-ref/source/v1/samples/job-create-request.json
+++ b/api-ref/source/v1/samples/job-create-request.json
@ -0,0 +1,24 @@
+{
+    "description": "Test-0001",
+    "job_schedule": {
+        "schedule_interval": "5 minutes",
+        "status": "scheduled",
+        "event": "start"
+    },
+    "job_actions": [
+        {
+            "max_retries": 5,
+            "max_retries_interval": 6,
+            "freezer_action": {
+                "backup_name": "test0001_backup",
+                "container": "test0001_container",
+                "no_incremental": true,
+                "path_to_backup": "/etc/",
+                "log_file": "/home/saad/job0001.log",
+                "snapshot": true,
+                "action": "backup",
+                "remove_older_than": 365
+            }
+        }
+]
+}
--- a/api-ref/source/v1/samples/job-get-response.json
+++ b/api-ref/source/v1/samples/job-get-response.json
@ -0,0 +1,41 @@
+{
+        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+        "description": "Test-0001",
+        "_version": 83,
+        "job_schedule":
+        {
+            "schedule_interval": "2 minutes",
+            "status": "scheduled",
+            "time_started": 1493119341,
+            "time_created": 1493051865,
+            "time_ended": 1493119342,
+            "result": "success",
+            "current_pid": 10058,
+            "event": ""
+        },
+        "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
+        "project_id": "752d8bd43d654e7a840bbfda77ce41af",
+        "job_actions":
+        [
+            {
+                "freezer_action":
+                {
+                    "backup_name": "test0001_backup",
+                    "container": "/tmp/test0001_container",
+                    "no_incremental": true,
+                    "path_to_backup": "/etc/",
+                    "storage": "local",
+                    "log_file": "/home/saad/job0001.log",
+                    "snapshot": false,
+                    "action": "backup",
+                    "remove_older_than": 365,
+                    "project_id": "752d8bd43d654e7a840bbfda77ce41af"
+                },
+                "max_retries": 5,
+                "max_retries_interval": 6,
+                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+                "action_id": "280d51d041ce4d4da8a386e96263f759"
+            }
+        ],
+        "job_id": "0ae284d514eb47dd84154748b5056749"
+}
--- a/api-ref/source/v1/samples/job-update-request.json
+++ b/api-ref/source/v1/samples/job-update-request.json
@ -0,0 +1,27 @@
+{
+    "description": "Test-0001",
+    "job_schedule": {
+        "schedule_interval": "5 minutes",
+        "status": "scheduled",
+        "event": "stop"
+    },
+    "project_id": "752d8bd43d654e7a840bbfda77ce41af",
+    "job_actions": [
+        {
+            "max_retries": 10,
+            "max_retries_interval": 10,
+            "freezer_action": {
+                "backup_name": "test0001_backup",
+                "container": "/tmp/xyzxyzxyz",
+                "storage": "local",
+                "no_incremental": true,
+                "path_to_backup": "/etc/",
+                "log_file": "/home/saad/job0001.log",
+                "snapshot": false,
+                "action": "backup",
+                "remove_older_than": 365,
+                "project_id": "752d8bd43d654e7a840bbfda77ce41af"
+            }
+        }
+]
+}
--- a/api-ref/source/v1/samples/job-update-response.json
+++ b/api-ref/source/v1/samples/job-update-response.json
@ -0,0 +1 @@
+{"job_id": "0ae284d514eb47dd84154748b5056749", "version": "3"}
--- a/api-ref/source/v1/samples/jobs-list-response.json
+++ b/api-ref/source/v1/samples/jobs-list-response.json
@ -0,0 +1,44 @@
+{
+        "jobs":
+        [
+            {
+                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+                "description": "Test-0001",
+                "job_schedule":
+                {
+                    "schedule_interval": "50 minutes",
+                    "status": "scheduled",
+                    "time_started": 1493055141,
+                    "time_created": 1493051865,
+                    "time_ended": 1493055142,
+                    "result": "success",
+                    "current_pid": 16793,
+                    "event": ""
+                },
+                "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
+                "job_actions":
+                [
+                    {
+                        "freezer_action":
+                        {
+                            "backup_name": "test0001_backup",
+                            "container": "/tmp/test0001_container",
+                            "no_incremental": true,
+                            "path_to_backup": "/etc/",
+                            "storage": "local",
+                            "log_file": "/home/saad/job0001.log",
+                            "snapshot": false,
+                            "action": "backup",
+                            "remove_older_than": 365
+                        },
+                        "max_retries": 5,
+                        "max_retries_interval": 6,
+                        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+                        "action_id": "280d51d041ce4d4da8a386e96263f759"
+                    }
+                ],
+                "job_id": "0ae284d514eb47dd84154748b5056749"
+            }
+        ]
+}
+
--- a/api-ref/source/v1/samples/session-start-request.json
+++ b/api-ref/source/v1/samples/session-start-request.json
@ -0,0 +1,6 @@
+{
+   "start":{
+      "job_id":"",
				`@ -0,0 +1 @@`
				`{"client_id": "752d8cd43d654e7a840bbfd277ce41af_szaher01"}`
				`@ -0,0 +1 @@`
				`{"job_id": "0ae284d514eb47dd84154748b5056749", "version": "3"}`