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

api-ref/source/conf.py

@@ -1,20 +1,47 @@
-"""
+# -*- coding: utf-8 -*-
-(c) Copyright 2016 Hewlett-Packard Enterprise Development Company, L.P.
+#
-Licensed under the Apache License, Version 2.0 (the "License");
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
-you may not use this file except in compliance with the License.
+# not use this file except in compliance with the License. You may obtain
-You may obtain a copy of the License at
+# 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
+#    http://www.apache.org/licenses/LICENSE-2.0
-distributed under the License is distributed on an "AS IS" BASIS,
+#
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# Unless required by applicable law or agreed to in writing, software
-See the License for the specific language governing permissions and
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-limitations under the License.
+# 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
+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",
+}
 
 # 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
@@ -28,18 +55,6 @@ sys.path.insert(0, os.path.abspath('./'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 
-import openstackdocstheme
-
-extensions = [
-    'os_api_ref',
-]
-
-html_theme = 'openstackdocs'
-html_theme_path = [openstackdocstheme.get_html_theme_path()]
-html_theme_options = {
-    "sidebar_mode": "toc",
-}
-
 # 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",
+git_cmd = [
-           "-n1"]
+    "git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", "-n1"
-html_last_updated_fmt = subprocess.Popen(
+]
-    git_cmd, stdout=subprocess.PIPE).communicate()[0]
+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 '
+    ('index', 'Freezerapi.tex', u'OpenStack Backup and Disaster Recovery '
-                             u'API Documentation', u'OpenStack Foundation',
+                                u'Service API Documentation',
-     'manual'),
+     u'OpenStack Foundation', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

api-ref/source/index.rst

@@ -1,20 +1,26 @@
 ..
-      (c) Copyright 2016 Hewlett-Packard Enterprise Development Company, L.P.
+      Copyright 2010 OpenStack Foundation
-      Licensed under the Apache License, Version 2.0 (the "License");
+      All Rights Reserved.
-      you may not use this file except in compliance with the License.
+
-      You may obtain a copy of the License at
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
-                   http://www.apache.org/licenses/LICENSE-2.0
+      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,
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-      See the License for the specific language governing permissions and
+      License for the specific language governing permissions and limitations
-      limitations under the License.
+      under the License.
-
-:tocdepth: 2
-
 
 ==========================
 Backup and DR Service APIs
 ==========================
 
-.. include:: versions.inc
+.. toctree::
+   :maxdepth: 2
+
+   versions/index
+   v1/index
+   v2/index

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.

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.

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.

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.

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

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.

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.

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
+}

api-ref/source/v1/samples/actions-create-response.json

@@ -0,0 +1,4 @@
+{
+        "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
+}
+

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"
+}

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"
+            }
+        ]
+}

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
+}

api-ref/source/v1/samples/actions-update-response.json

@@ -0,0 +1,5 @@
+{
+  "version": 2,
+  "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
+}
+

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
+}
+

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"
+    }
+  ]
+}

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"
+}
+

api-ref/source/v1/samples/clients-create-request.json

@@ -0,0 +1,8 @@
+{
+            "client":
+            {
+                "hostname": "szaher01",
+                "uuid": "c4031a4885384376a717a238de975a9c"
+            },
+            "client_id": "752d8cd43d654e7a840bbfd277ce41af_szaher01"
+}

api-ref/source/v1/samples/clients-create-response.json

@@ -0,0 +1 @@
+{"client_id": "752d8cd43d654e7a840bbfd277ce41af_szaher01"}

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"
+            }
+        ]
+}

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
+            }
+        }
+]
+}

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"
+}

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"
+            }
+        }
+]
+}

api-ref/source/v1/samples/job-update-response.json

@@ -0,0 +1 @@
+{"job_id": "0ae284d514eb47dd84154748b5056749", "version": "3"}

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"
+            }
+        ]
+}
+

api-ref/source/v1/samples/session-start-request.json

@@ -0,0 +1,6 @@
+{
+   "start":{
+      "job_id":"",
+      "current_tag":20
+   }
+}

api-ref/source/v1/samples/session-start-response.json

@@ -0,0 +1,4 @@
+{
+  "result": "success",
+  "session_tag": 21
+}

api-ref/source/v1/samples/sessions-create-request.json

@@ -0,0 +1,10 @@
+{
+   "session_tag":20,
+   "description":"Webapp Database backup ",
+   "hold_off":30,
+   "schedule":{
+      "schedule_interval":"1 hours",
+      "status":"scheduled",
+      "event":"start"
+   }
+}

api-ref/source/v1/samples/sessions-create-response.json

@@ -0,0 +1,4 @@
+{
+        "session_id": "79eba555449d4cfe8ef66f34cb096295"
+}
+

api-ref/source/v1/samples/sessions-get-response.json

@@ -0,0 +1,15 @@
+{
+        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+        "description": "Instance Database backup ",
+        "schedule":
+        {
+            "schedule_interval": "1 days",
+            "status": "scheduled",
+            "event": "start"
+        },
+        "_version": 2,
+        "session_tag": 250,
+        "session_id": "79eba555449d4cfe8ef66f34cb096295",
+        "hold_off": 50
+}
+

api-ref/source/v1/samples/sessions-get-with-job-response.json

@@ -0,0 +1,25 @@
+{
+        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+        "description": "Instance Database backup ",
+        "schedule":
+        {
+            "schedule_interval": "1 days",
+            "status": "scheduled",
+            "event": "start"
+        },
+        "_version": 3,
+        "session_tag": 250,
+        "session_id": "79eba555449d4cfe8ef66f34cb096295",
+        "jobs":
+        {
+            "0ae284d514eb47dd84154748b5056749":
+            {
+                "time_ended": 1493119342,
+                "status": "scheduled",
+                "result": "success",
+                "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
+                "time_started": 1493119341
+            }
+        },
+        "hold_off": 50
+}

api-ref/source/v1/samples/sessions-list-response.json

@@ -0,0 +1,29 @@
+{
+        "sessions":
+        [
+            {
+                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
+                "description": "Instance Database backup ",
+                "schedule":
+                {
+                    "schedule_interval": "1 days",
+                    "status": "scheduled",
+                    "event": "start"
+                },
+                "session_tag": 250,
+                "session_id": "79eba555449d4cfe8ef66f34cb096295",
+                "jobs":
+                {
+                    "0ae284d514eb47dd84154748b5056749":
+                    {
+                        "time_ended": 1493119342,
+                        "status": "scheduled",
+                        "result": "success",
+                        "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
+                        "time_started": 1493119341
+                    }
+                },
+                "hold_off": 50
+            }
+        ]
+}

api-ref/source/v1/samples/sessions-update-request.json

@@ -0,0 +1,10 @@
+{
+  "session_tag": 250,
+  "description": "Instance Database backup ",
+  "hold_off": 50,
+  "schedule": {
+        "schedule_interval": "1 days",
+        "status": "scheduled",
+        "event": "start"
+  }
+}

api-ref/source/v1/samples/sessions-update-response.json

@@ -0,0 +1,5 @@
+{
+        "version": 5,
+        "session_id": "0ec2c71697464d63813b419d2282a43a"
+}
+

api-ref/source/v1/sessions-v1.inc

@@ -0,0 +1,323 @@
+===================
+Sessions (sessions)
+===================
+
+A session is a group of jobs which share the same scheduling time. A session
+is identified by its ``session_id`` and has a numeric tag (session_tag) which
+is incremented each time that a new session is started. The purpose of the
+``session_tag`` is that of identifying a group of jobs which have been
+executed together and which therefore represent a snapshot of a distributed
+system.
+
+When a ``job`` is added to a session, the scheduling time of the session is
+copied into the job data structure, so that any job belonging to the same
+session will start at the same time.
+
+
+Lists Sessions
+==============
+
+.. rest_method::  GET /v1/sessions
+
+Lists sessions.
+
+This operation lists sessions.
+
+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
+
+  - sessions: sessions
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/sessions-list-response.json
+   :language: javascript
+
+
+Creates session
+===============
+
+.. rest_method:: POST /v1/sessions
+
+Creates a session.
+
+This operation creates a new session.
+
+Normal response codes: 201
+
+Error response codes:
+
+- Syntax Error (753)
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - description: session_description
+  - hold_off: session_hold_off
+  - session_tag: session_tag
+  - schedule: session_schedule
+  - schedule_internval: session_schedule_internval
+  - event: session_event
+
+Request Example
+---------------
+
+.. literalinclude:: samples/sessions-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - session_id: session_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/sessions-create-response.json
+   :language: javascript
+
+
+Show sessions
+=============
+
+.. rest_method::  GET /v1/sessions/{session_id}
+
+Shows sessions.
+
+This operation shows a certain session. It displays all session details
+with jobs included in this session.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - session_id: session_id_path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - user_id: user_id
+  - description: session_description
+  - schedule: session_schedule
+  - session_tag: session_tag
+  - session_id: session_id
+  - hold_off: session_hold_off
+
+Response Example
+----------------
+
+.. literalinclude:: samples/sessions-get-response.json
+   :language: javascript
+
+.. literalinclude:: samples/sessions-get-with-job-response.json
+   :language: javascript
+
+
+
+Updates a session
+==================
+
+.. rest_method:: PATCH /v1/sessions
+
+Updates a session.
+
+This operation updates a new session.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Syntax Error (753)
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - description: session_description
+  - hold_off: session_hold_off
+  - session_tag: session_tag
+  - schedule: session_schedule
+  - schedule_internval: session_schedule_internval
+  - event: session_event
+  - session_id: session_id_path
+
+Request Example
+---------------
+
+.. literalinclude:: samples/sessions-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - session_id: session_id
+  - version: version_doc
+
+Response Example
+----------------
+
+.. literalinclude:: samples/sessions-update-response.json
+   :language: javascript
+
+
+Add jobs
+========
+
+.. rest_method::  PUT /v1/sessions/{session_id}/jobs/{job_id}
+
+attaches job to a session.
+
+This operation adds a certain job to a session. The api will load the job
+and the session and add the job to session document.
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - session_id: session_id_path
+  - job_id: job_id_path
+
+No response will be returned for this job.
+
+
+Remove jobs
+===========
+
+.. rest_method::  DELETE /v1/sessions/{session_id}/jobs/{job_id}
+
+Removes a job from a session.
+
+This operation will remove a certain job to a session.
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - session_id: session_id_path
+  - job_id: job_id_path
+
+No response will be returned for this job.
+
+
+Start sessions
+==============
+
+.. rest_method::  POST /v1/sessions/{session_id}/actions
+
+Removes a job from a session.
+
+This operation will remove a certain job to a session.
+
+Normal response codes: 202
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - session_id: session_id_path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - result: result
+  - session_tag: session_tag
+
+Response Example
+----------------
+
+.. literalinclude:: samples/session-start-response.json
+   :language: javascript
+
+
+Remove sessions
+===============
+
+.. rest_method::  DELETE /v1/sessions/{session_id}
+
+Removes a session.
+
+This operation will remove a certain a session.
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - session_id: session_id_path
+
+No response will be returned for this job.

api-ref/source/v2/backups-v2.inc

@@ -0,0 +1,53 @@
+=================
+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.
+
+List backups
+============
+
+.. rest_method::  GET /v2/{project_id}/backups
+
+Lists backups.
+
+This operation lists backups for the project. The backups are sorted
+alphabetically by name.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - project_id: project_id_path
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - marker: marker
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - backups: backups
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/backup-list-response.json
+   :language: javascript
+

api-ref/source/v2/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 v2 (EXPERIMENTAL)
+====================================
+
+.. rest_expand_all::
+
+.. include:: backups-v2.inc
+.. include:: clients-v2.inc
+.. include:: jobs-v2.inc
+.. include:: actions-v2.inc
+.. include:: sessions-v2.inc

api-ref/source/v2/jobs-v2.inc

@@ -0,0 +1,103 @@
+===========
+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.
+
+List jobs
+=========
+
+.. rest_method::  GET /v2/{project_id}/jobs
+
+Lists jobs v2.
+
+This operation lists jobs for the project. The jobs are sorted alphabetically
+ by name.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - project_id: project_id_path
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - marker: marker
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - jobs: jobs
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/jobs-list-response.json
+   :language: javascript
+
+
+Create job
+==========
+
+.. rest_method:: POST /v2/{project_id}/jobs
+
+Creates a job v2.
+
+This operation creates a new job.
+
+The ``body`` attribute specifies contains a set of actions that gets created
+ one the job is submitted.
+
+``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:
+
+- 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
+  - project_id: project_id_path
+
+Request Example
+---------------
+
+.. literalinclude:: samples/job-create-request.json
+   :language: javascript
+
+
+This operation does not return a response body.

api-ref/source/v2/parameters.yaml

@@ -0,0 +1,68 @@
+###############################  Response  ####################################
+
+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
+
+project_id_path:
+  type: string
+  in: query
+  required: true
+  description: |
+    The UUID of the project. A project was also known as
+    a tenant.
+
+backups:
+  type: list
+  in: body
+  description: |
+    A list of backups
+
+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_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
+
+versions:
+  type: list
+  in: body
+  required: True
+  description: |
+    A list of supported major API versions.

api-ref/source/v2/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"
+    }
+  ]
+}

api-ref/source/v2/samples/job-create-request.json

@@ -0,0 +1,26 @@
+{
+    "description": "Test-0001",
+    "job_schedule": {
+        "schedule_interval": "5 minutes",
+        "status": "scheduled",
+        "event": "start"
+    },
+    "project_id": "752d8bd43d654e7a840bbfda77ce41af",
+    "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,
+                "project_id": "752d8bd43d654e7a840bbfda77ce41af"
+            }
+        }
+]
+}

api-ref/source/v2/samples/jobs-list-response.json

@@ -0,0 +1,46 @@
+{
+        "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",
+                "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"
+            }
+        ]
+}
+

api-ref/source/versions/index.rst

@@ -0,0 +1,20 @@
+..
+      (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.
+
+:tocdepth: 2
+
+
+==============================
+Backup and DR Service Versions
+==============================
+
+.. include:: versions.inc

api-ref/source/versions/parameters.yaml

@@ -0,0 +1,40 @@
+###############################  Response  ####################################
+
+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
+
+project_id_path:
+  type: string
+  in: query
+  description: |
+    The UUID of the project. A project was also known as
+    a tenant.
+
+backups:
+  type: list
+  in: body
+  description: |
+    A list of backups
+
+versions:
+  type: list
+  in: body
+  required: True
+  description: |
+    A list of supported major API versions.

api-ref/source/versions/versions.inc

@@ -2,7 +2,7 @@
 API Versions
 ============
 
-The Freezer API only supports v1.
+Freezer API supports v1 and v2.
 
 
 List major versions

install-guide/source/index.rst

@@ -18,4 +18,4 @@ Backup/Restore and DR service
 
 This chapter assumes a working setup of OpenStack following the
 `OpenStack Installation Tutorial
-<https://docs.openstack.org/project-install-guide/ocata/>`_.
+<https://docs.openstack.org/project-install-guide/ocata/>`_.

install-guide/source/install.rst

@@ -172,4 +172,4 @@ API registration
 
 .. toctree::
 
-   devstack_plugin.rst
+   devstack_plugin.rst