680 lines
20 KiB
ReStructuredText
680 lines
20 KiB
ReStructuredText
**************
|
|
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
|
|
}
|
|
|
|
|