freezer service API v1 specification reformatted
New documentation in rst format and with proper file name It includes the following routes: /v1/backups /v1/clients /v1/jobs Change-Id: I29c33aabba942c0d9fa700dc7972bce3b2daea99
This commit is contained in:
Fabrizio Vanni
parent
f4a9d19a12
commit
4423f1c8f1
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1,679 @@
|
|||
**************
|
||||
Freezer API v1
|
||||
**************
|
||||
|
||||
1. API versions
|
||||
===============
|
||||
|
||||
========= ========== ===============================================
|
||||
Method URI Description
|
||||
========= ========== ===============================================
|
||||
GET / List information about freezer API versions
|
||||
========= ========== ===============================================
|
||||
|
||||
|
||||
1.1 Request
|
||||
-----------
|
||||
This operation does not accept a body
|
||||
|
||||
1.2 Response
|
||||
------------
|
||||
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"versions": [
|
||||
{
|
||||
"id": "1",
|
||||
"links": [
|
||||
{
|
||||
"href": "/v1/",
|
||||
"rel": "self"
|
||||
}
|
||||
],
|
||||
"status": "CURRENT",
|
||||
"updated": "2015-03-23T13:45:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
2. API doc home
|
||||
===============
|
||||
|
||||
========= ========== ===============================================
|
||||
Method URI Description
|
||||
========= ========== ===============================================
|
||||
GET /v1 Provides information about how to interact
|
||||
with the freezer API server
|
||||
========= ========== ===============================================
|
||||
|
||||
2.1 Request
|
||||
-----------
|
||||
This operation does not accept a body
|
||||
|
||||
2.2 Response
|
||||
------------
|
||||
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
}
|
||||
"resources": {
|
||||
"rel/backups": {
|
||||
"hints": {
|
||||
"allow": [
|
||||
"GET"
|
||||
],
|
||||
"formats": {
|
||||
"application/json": {}
|
||||
}
|
||||
},
|
||||
"href-template": "/v1/backups/{backup_id}",
|
||||
"href-vars": {
|
||||
"backup_id": "param/backup_id"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
3. Backups
|
||||
==========
|
||||
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
POST /v1/backups creates a backup entry in the API storage
|
||||
------- --------------------------- -----------------------------------------------
|
||||
GET /v1/backups{?limit,offset} List backup information
|
||||
------- --------------------------- -----------------------------------------------
|
||||
GET /v1/backups/{backup_id} Get details for a specific backup
|
||||
------- --------------------------- -----------------------------------------------
|
||||
DELETE /v1/backups/{backup_id} Deletes the specific backup information
|
||||
======= =========================== ===============================================
|
||||
|
||||
|
||||
3.1 Create backup information entry
|
||||
-----------------------------------
|
||||
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
POST /v1/backups creates a backup entry in the API storage
|
||||
======= =========================== ===============================================
|
||||
|
||||
Normal response codes: 201
|
||||
|
||||
3.1.1 Request
|
||||
-------------
|
||||
|
||||
Example. Uploading backup metadata
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"backup_name": "important_data_backup",
|
||||
"backup_session": 12344311,
|
||||
"backup_size_compressed": 1212,
|
||||
"backup_size_uncompressed": 1212,
|
||||
"client_os": "linux",
|
||||
"compression_alg": "None",
|
||||
"container": "freezer_container",
|
||||
"encrypted": "false",
|
||||
"fs_real_path": "/blabla",
|
||||
"host_name": "alpha",
|
||||
"level": 0,
|
||||
"max_level": 5,
|
||||
"mode": "fs",
|
||||
"timestamp": 123444311,
|
||||
"total_backup_session_size": 1212,
|
||||
"total_broken_links": 0,
|
||||
"total_directories": 2,
|
||||
"total_fs_files": 11,
|
||||
"vol_snap_path": "/blablasnap"
|
||||
}
|
||||
|
||||
3.1.2 Response
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"backup_id": "freezer_container_alpha_important_data_backup_123444324_1"
|
||||
}
|
||||
|
||||
3.2 List backup information
|
||||
---------------------------
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
GET /v1/backups{?limit,offset} List backup information
|
||||
======= =========================== ===============================================
|
||||
|
||||
Normal response codes:200
|
||||
|
||||
3.2.1 Request
|
||||
-------------
|
||||
|
||||
This operation does not accept a bode
|
||||
|
||||
3.2.2 Response
|
||||
--------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"backups": [
|
||||
{
|
||||
"backup_id":
|
||||
"freezer_container_alpha_important_data_backup_123444324_1",
|
||||
"backup_metadata": {
|
||||
"backup_name": "important_data_backup",
|
||||
"backup_session": 12344321,
|
||||
"backup_size_compressed": 1212,
|
||||
"backup_size_uncompressed": 1212,
|
||||
"client_os": "linux",
|
||||
"compression_alg": "None",
|
||||
"container": "freezer_container",
|
||||
"encrypted": "false",
|
||||
"fs_real_path": "/blabla",
|
||||
"host_name": "alpha",
|
||||
"level": 1,
|
||||
"max_level": 5,
|
||||
"mode": "fs",
|
||||
"timestamp": 123444324,
|
||||
"total_backup_session_size": 1212,
|
||||
"total_broken_links": 0,
|
||||
"total_directories": 2,
|
||||
"total_fs_files": 11,
|
||||
"vol_snap_path": "/blablasnap"
|
||||
}
|
||||
},
|
||||
{
|
||||
"backup_id":
|
||||
"freezer_container_alpha_important_data_backup_123444311_0",
|
||||
"backup_metadata": {
|
||||
"backup_name": "important_data_backup",
|
||||
"backup_session": 12344311,
|
||||
"backup_size_compressed": 1212,
|
||||
"backup_size_uncompressed": 1212,
|
||||
"client_os": "linux",
|
||||
"compression_alg": "None",
|
||||
"container": "freezer_container",
|
||||
"encrypted": "false",
|
||||
"fs_real_path": "/blabla",
|
||||
"host_name": "alpha",
|
||||
"level": 0,
|
||||
"max_level": 5,
|
||||
"mode": "fs",
|
||||
"timestamp": 123444311,
|
||||
"total_backup_session_size": 1212,
|
||||
}
|
||||
}
|
||||
]
|
||||
"total_broken_links": 0,
|
||||
"total_directories": 2,
|
||||
"total_fs_files": 11,
|
||||
"vol_snap_path": "/blablasnap"
|
||||
}
|
||||
|
||||
3.3 Get backup details
|
||||
----------------------
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
GET /v1/backups/{backup_id} Get details for a specific backup
|
||||
======= =========================== ===============================================
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
3.3.1 Request
|
||||
-------------
|
||||
This operation does not accept a body
|
||||
|
||||
3.3.2 Response
|
||||
--------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
|
||||
{
|
||||
"backup_id": "freezer_container_alpha_important_data_backup_123444311_0",
|
||||
"backup_metadata": {
|
||||
"backup_name": "important_data_backup",
|
||||
"backup_session": 12344311,
|
||||
"backup_size_compressed": 1212,
|
||||
"backup_size_uncompressed": 1212,
|
||||
"client_os": "linux",
|
||||
"compression_alg": "None",
|
||||
"container": "freezer_container",
|
||||
"encrypted": "false",
|
||||
"fs_real_path": "/blabla",
|
||||
"host_name": "alpha",
|
||||
"level": 0,
|
||||
"max_level": 5,
|
||||
"mode": "fs",
|
||||
"timestamp": 123444311,
|
||||
"total_backup_session_size": 1212,
|
||||
"total_broken_links": 0,
|
||||
"total_directories": 2,
|
||||
"total_fs_files": 11,
|
||||
"vol_snap_path": "/blablasnap"
|
||||
}
|
||||
}
|
||||
|
||||
3.4 Delete backup information
|
||||
-----------------------------
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
DELETE /v1/backups/{backup_id} Deletes the specific backup information
|
||||
======= =========================== ===============================================
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
3.4.1 Request
|
||||
-------------
|
||||
This operation does not accept a body
|
||||
|
||||
3.4.2 Response
|
||||
--------------
|
||||
This operation does not return a body
|
||||
|
||||
4 Clients
|
||||
=========
|
||||
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
GET /v1/clients(?limit,offset) Lists registered clients
|
||||
------- --------------------------- -----------------------------------------------
|
||||
GET /v1/clients/{client_id} Get client details
|
||||
------- --------------------------- -----------------------------------------------
|
||||
POST /v1/clients Creates client entry
|
||||
------- --------------------------- -----------------------------------------------
|
||||
DELETE /v1/clients/{freezerc_id} Deletes the specified client information
|
||||
======= =========================== ===============================================
|
||||
|
||||
4.1 List registered clients
|
||||
---------------------------
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
GET /v1/clients(?limit,offset) Lists registered clients
|
||||
======= =========================== ===============================================
|
||||
|
||||
4.1.1 Request
|
||||
-------------
|
||||
This operation does not accept a body
|
||||
|
||||
4.1.2 Response
|
||||
--------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"clients":
|
||||
[
|
||||
{
|
||||
"client":
|
||||
{
|
||||
"hostname": "my-workstation",
|
||||
"description": "my simple freezer client description",
|
||||
"client_id": "5c869f05e23149e4bf18639f2dd96380_vannif-HP-Z420-Workstation"
|
||||
},
|
||||
"user_id": "fe93b43c374247c38b456c08041e6765"
|
||||
},
|
||||
{
|
||||
"client":
|
||||
{
|
||||
"hostname": "another-node",
|
||||
"description": "my second workstation",
|
||||
"client_id": "5c869f05e23149e4bf18639f2dd96380_another-node"
|
||||
},
|
||||
"user_id": "fe93b43c374247c38b456c08041e6765"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
4.2 Get client details
|
||||
----------------------
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
GET /v1/clients/{client_id} Get client details
|
||||
======= =========================== ===============================================
|
||||
|
||||
4.2.1 Request
|
||||
-------------
|
||||
This operation does not accept a body
|
||||
|
||||
4.2.2 Response
|
||||
--------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
u'client': {
|
||||
u'client_id': u'5c869f05e23149e4bf18639f2dd96380_my-workstation',
|
||||
u'description': u'my simple freezer client description',
|
||||
u'hostname': u'my-workstation',
|
||||
},
|
||||
u'user_id': u'fe93b43c374247c38b456c08041e6765',
|
||||
}
|
||||
|
||||
4.3 Creates client entry
|
||||
------------------------
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
POST /v1/clients Creates client entry
|
||||
======= =========================== ===============================================
|
||||
|
||||
4.3.1 Request
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"hostname": "my-workstation",
|
||||
"description": "my simple freezer client description",
|
||||
"client_id": "5c869f05e23149e4bf18639f2dd96380_my-workstation"
|
||||
}
|
||||
|
||||
4.3.2 Response
|
||||
--------------
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"client_id": "5c869f05e23149e4bf18639f2dd96380_my-workstation"
|
||||
}
|
||||
|
||||
|
||||
4.4 Deletes the specified client information
|
||||
--------------------------------------------
|
||||
======= =========================== ===============================================
|
||||
Method URI Description
|
||||
======= =========================== ===============================================
|
||||
DELETE /v1/clients/{client_id} Deletes the specified client information
|
||||
======= =========================== ===============================================
|
||||
|
||||
4.4.1 Request
|
||||
-------------
|
||||
This operation does not accept a body
|
||||
|
||||
4.4.2 Response
|
||||
--------------
|
||||
This operation does not return a body
|
||||
|
||||
5 Jobs
|
||||
======
|
||||
|
||||
======= ========================== ===============================================
|
||||
Method URI Description
|
||||
======= ========================== ===============================================
|
||||
GET /v1/jobs(?limit,offset) Lists registered jobs
|
||||
------- -------------------------- -----------------------------------------------
|
||||
GET /v1/jobs/{jobs_id} Get job details
|
||||
------- -------------------------- -----------------------------------------------
|
||||
POST /v1/jobs Creates job entry
|
||||
------- -------------------------- -----------------------------------------------
|
||||
POST /v1/jobs/{jobs_id} creates or replaces a job entry
|
||||
using the specified job_id
|
||||
------- -------------------------- -----------------------------------------------
|
||||
DELETE /v1/jobs/{jobs_id} Deletes the specified job information
|
||||
------- -------------------------- -----------------------------------------------
|
||||
PATCH /v1/jobs/{jobs_id} Updates part of the document
|
||||
======= ========================== ===============================================
|
||||
|
||||
5.1 Lists registered jobs
|
||||
-------------------------
|
||||
======= ========================== ===============================================
|
||||
Method URI Description
|
||||
======= ========================== ===============================================
|
||||
GET /v1/jobs(?limit,offset) Lists registered jobs
|
||||
======= ========================== ===============================================
|
||||
|
||||
5.1.1 Request
|
||||
-------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"match": [
|
||||
{
|
||||
"client_id": "5c869f05e23149e4bf18639f2dd96380_my-workstation"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
5.1.2 Response
|
||||
--------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"jobs": [
|
||||
{
|
||||
u'client_id': u'5c869f05e23149e4bf18639f2dd96380_my-workstation',
|
||||
u'job_action': {
|
||||
u'action': u'backup',
|
||||
u'backup_name': u'workday_backup_of_my_work_stuff',
|
||||
u'container': u'my_backups',
|
||||
u'max_level': u'4',
|
||||
u'path_to_backup': u'/home/me/work_stuff',
|
||||
},
|
||||
u'job_id': u'685eab6e3a2744b6bce789fe7e71d6e7',
|
||||
u'job_schedule': {
|
||||
u'schedule_day_of_week': u'tue,wed,thu,fri,sat',
|
||||
u'schedule_hour': u'03',
|
||||
u'schedule_minute': u'20',
|
||||
u'time_created': 1435064743,
|
||||
u'time_ended': -1,
|
||||
u'time_started': -1,
|
||||
},
|
||||
u'user_id': u'fe93b43c374247c38b456c08041e6765',
|
||||
},
|
||||
{
|
||||
u'client_id': u'5c869f05e23149e4bf18639f2dd96380_my-workstation',
|
||||
u'job_action': {
|
||||
u'action': u'backup',
|
||||
u'backup_name': u'daily_backup_my_documents',
|
||||
u'container': u'my_backups',
|
||||
u'max_level': u'7',
|
||||
u'path_to_backup': u'/home/me/my_documents',
|
||||
},
|
||||
u'job_id': u'a4ff2f1937864470b8f35e69c59454fa',
|
||||
u'job_schedule': {
|
||||
u'schedule_interval': u'1 days',
|
||||
u'schedule_start_date': u'2015-06-02T03:20:00',
|
||||
u'time_created': 1435064743,
|
||||
u'time_ended': -1,
|
||||
u'time_started': -1,
|
||||
},
|
||||
u'user_id': u'fe93b43c374247c38b456c08041e6765',
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
5.2 Get job details
|
||||
-------------------
|
||||
======= ========================== ===============================================
|
||||
Method URI Description
|
||||
======= ========================== ===============================================
|
||||
GET /v1/jobs/{jobs_id} Get job details
|
||||
======= ========================== ===============================================
|
||||
|
||||
5.2.1 Request
|
||||
-------------
|
||||
This operation does not accept a body
|
||||
|
||||
5.2.2 Response
|
||||
--------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
u'client_id': u'5c869f05e23149e4bf18639f2dd96380_my-workstation',
|
||||
u'job_id': u'685eab6e3a2744b6bce789fe7e71d6e7',
|
||||
u'user_id': u'fe93b43c374247c38b456c08041e6765',
|
||||
u'job_action': {
|
||||
u'action': u'backup',
|
||||
u'backup_name': u'workday_backup_of_my_work_stuff',
|
||||
u'container': u'my_backups',
|
||||
u'max_level': u'4',
|
||||
u'path_to_backup': u'/home/me/work_stuff',
|
||||
},
|
||||
u'job_schedule': {
|
||||
u'schedule_day_of_week': u'tue,wed,thu,fri,sat',
|
||||
u'schedule_hour': u'03',
|
||||
u'schedule_minute': u'20',
|
||||
u'time_created': 1435064743,
|
||||
u'time_ended': -1,
|
||||
u'time_started': -1,
|
||||
}
|
||||
}
|
||||
|
||||
5.3 Creates job entry
|
||||
---------------------
|
||||
======= ========================== ===============================================
|
||||
Method URI Description
|
||||
======= ========================== ===============================================
|
||||
POST /v1/jobs Creates job entry
|
||||
======= ========================== ===============================================
|
||||
|
||||
5.3.1 Request
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
u'client_id': u'5c869f05e23149e4bf18639f2dd96380_my-workstation',
|
||||
u'job_action': {
|
||||
u'action': u'backup',
|
||||
u'backup_name': u'workday_backup_of_my_work_stuff',
|
||||
u'container': u'my_backups',
|
||||
u'max_level': u'4',
|
||||
u'path_to_backup': u'/home/me/work_stuff',
|
||||
},
|
||||
u'job_schedule': {
|
||||
u'schedule_day_of_week': u'tue,wed,thu,fri,sat',
|
||||
u'schedule_hour': u'03',
|
||||
u'schedule_minute': u'20',
|
||||
},
|
||||
}
|
||||
|
||||
5.3.2 Response
|
||||
--------------
|
||||
Example
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"job_id": "685eab6e3a2744b6bce789fe7e71d6e7"
|
||||
}
|
||||
|
||||
5.4 Creates or replaces a job entry
|
||||
-----------------------------------
|
||||
======= ========================== ===============================================
|
||||
Method URI Description
|
||||
======= ========================== ===============================================
|
||||
POST /v1/jobs/{jobs_id} creates or replaces a job entry
|
||||
using the specified job_id
|
||||
======= ========================== ===============================================
|
||||
|
||||
5.4.1 Request
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
u'client_id': u'5c869f05e23149e4bf18639f2dd96380_my-workstation',
|
||||
u'job_action': {
|
||||
u'action': u'backup',
|
||||
u'backup_name': u'workday_backup_of_my_work_stuff',
|
||||
u'container': u'my_backups',
|
||||
u'max_level': u'4',
|
||||
u'path_to_backup': u'/home/me/work_stuff',
|
||||
},
|
||||
u'job_schedule': {
|
||||
u'schedule_day_of_week': u'tue,wed,thu,fri,sat',
|
||||
u'schedule_hour': u'03',
|
||||
u'schedule_minute': u'20',
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
|
||||
5.4.2 Response
|
||||
--------------
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"job_id": "685eab6e3a2744b6bce789fe7e71d6e7",
|
||||
"version": "3"
|
||||
}
|
||||
|
||||
|
||||
5.5 Deletes the specified job information
|
||||
-----------------------------------------
|
||||
======= ========================== ===============================================
|
||||
Method URI Description
|
||||
======= ========================== ===============================================
|
||||
DELETE /v1/jobs/{jobs_id} Deletes the specified job information
|
||||
======= ========================== ===============================================
|
||||
|
||||
5.5.1 Request
|
||||
-------------
|
||||
This operation does not accept a body
|
||||
|
||||
5.5.2 Response
|
||||
--------------
|
||||
This operation does not return a body
|
||||
|
||||
5.6 Updates part of the document
|
||||
--------------------------------
|
||||
======= ========================== ===============================================
|
||||
Method URI Description
|
||||
======= ========================== ===============================================
|
||||
PATCH /v1/jobs/{jobs_id} Updates part of the document
|
||||
======= ========================== ===============================================
|
||||
|
||||
5.6.1 Request
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"job_schedule":
|
||||
{
|
||||
"event": "start"
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
5.6.2 Response
|
||||
--------------
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
"job_id": "923b9d436bca41d79007fe14bd103ed1",
|
||||
"version": 3
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue