From c22dc7babe8748f678ed91f999151bacb3c20687 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Guillot?= Date: Tue, 11 Apr 2017 14:51:00 -0400 Subject: [PATCH] Write doc without flask autodoc - remove inline docs from routes.py - correct certain response payloads - add all api docs to index.rst Change-Id: I58bb24f1a8ce173264ab9c1607cbe3af8d936fdb --- almanach/api/v1/routes.py | 273 ------- .../input/resize_instance-body.json | 4 - .../input/update_instance_entity-body.json | 4 - .../input/attach_volume-body.json | 0 .../input/create_instance-body.json | 2 +- .../input/create_volume-body.json | 0 .../input/create_volume_type-body.json | 0 .../input/delete_instance-body.json | 0 .../input/delete_volume-body.json | 0 .../input/detach_volume-body.json | 0 .../input/rebuild_instance-body.json | 0 .../input/resize_instance-body.json | 4 + .../input/resize_volume-body.json | 0 .../input/update_instance_entity-body.json | 4 + .../api_examples/output/entities.json | 0 .../api_examples/output/entity.json | 0 .../api_examples/output/info.json | 0 .../api_examples/output/instances.json | 2 +- .../output/update_instance_entity.json | 0 .../api_examples/output/volume_type.json | 0 .../api_examples/output/volume_types.json | 0 .../api_examples/output/volumes.json | 0 doc/source/conf.py | 4 +- doc/source/index.rst | 709 +++++++++++++++++- test-requirements.txt | 1 - 25 files changed, 717 insertions(+), 290 deletions(-) delete mode 100644 doc/api_examples/input/resize_instance-body.json delete mode 100644 doc/api_examples/input/update_instance_entity-body.json rename doc/{ => source}/api_examples/input/attach_volume-body.json (100%) rename doc/{ => source}/api_examples/input/create_instance-body.json (82%) rename doc/{ => source}/api_examples/input/create_volume-body.json (100%) rename doc/{ => source}/api_examples/input/create_volume_type-body.json (100%) rename doc/{ => source}/api_examples/input/delete_instance-body.json (100%) rename doc/{ => source}/api_examples/input/delete_volume-body.json (100%) rename doc/{ => source}/api_examples/input/detach_volume-body.json (100%) rename doc/{ => source}/api_examples/input/rebuild_instance-body.json (100%) create mode 100644 doc/source/api_examples/input/resize_instance-body.json rename doc/{ => source}/api_examples/input/resize_volume-body.json (100%) create mode 100644 doc/source/api_examples/input/update_instance_entity-body.json rename doc/{ => source}/api_examples/output/entities.json (100%) rename doc/{ => source}/api_examples/output/entity.json (100%) rename doc/{ => source}/api_examples/output/info.json (100%) rename doc/{ => source}/api_examples/output/instances.json (88%) rename doc/{ => source}/api_examples/output/update_instance_entity.json (100%) rename doc/{ => source}/api_examples/output/volume_type.json (100%) rename doc/{ => source}/api_examples/output/volume_types.json (100%) rename doc/{ => source}/api_examples/output/volumes.json (100%) diff --git a/almanach/api/v1/routes.py b/almanach/api/v1/routes.py index bd4ec98..c73feff 100644 --- a/almanach/api/v1/routes.py +++ b/almanach/api/v1/routes.py @@ -88,15 +88,6 @@ def authenticated(api_call): @api.route("/info", methods=["GET"]) @to_json def get_info(): - """Display information about the current version and counts of entities in the database. - - :code 200 OK: Service is available - - Example output: - - .. literalinclude:: ../api_examples/output/info.json - :language: json - """ return app_ctl.get_application_info() @@ -104,26 +95,6 @@ def get_info(): @authenticated @to_json def create_instance(project_id): - """Create an instance for a tenant. - - :arg uuid project_id: Tenant Uuid - :arg uuid id: The instance uuid - :arg datetime created_at: Y-m-d H:M:S.f - :arg uuid flavor: The flavor uuid - :arg str os_type: The OS type - :arg str os_distro: The OS distro - :arg str os_version: The OS version - :arg str name: The instance name - - :code 201 Created: Instance successfully created - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If tenant does not exist - - Example input: - - .. literalinclude:: ../api_examples/input/create_instance-body.json - :language: json - """ body = jsonutils.loads(flask.request.data) LOG.info("Creating instance for tenant %s with data %s", project_id, body) @@ -145,20 +116,6 @@ def create_instance(project_id): @authenticated @to_json def delete_instance(instance_id): - """Delete the instance. - - :arg uuid instance_id: Instance Uuid - :arg datetime date: Y-m-d H:M:S.f - - :code 202 Accepted: Instance successfully deleted - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If instance does not exist - - Example input: - - .. literalinclude:: ../api_examples/input/delete_instance-body.json - :language: json - """ data = jsonutils.loads(flask.request.data) LOG.info("Deleting instance with id %s with data %s", instance_id, data) instance_ctl.delete_instance( @@ -173,21 +130,6 @@ def delete_instance(instance_id): @authenticated @to_json def resize_instance(instance_id): - """Re-size an instance when the instance flavor was changed in OpenStack. - - :arg uuid instance_id: Instance Uuid - :arg datetime date: Y-m-d H:M:S.f - :arg uuid flavor: The flavor uuid - - :code 200 OK: Instance successfully re-sized - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If instance does not exist - - Example input: - - .. literalinclude:: ../api_examples/input/resize_instance-body.json - :language: json - """ instance = jsonutils.loads(flask.request.data) LOG.info("Resizing instance with id %s with data %s", instance_id, instance) instance_ctl.resize_instance( @@ -203,23 +145,6 @@ def resize_instance(instance_id): @authenticated @to_json def rebuild_instance(instance_id): - """Rebuild an instance when the instance image was changed in OpenStack. - - :arg uuid instance_id: Instance Uuid - :arg str distro: The OS distro - :arg str version: The OS version - :arg str os_type: The OS type - :arg datetime rebuild_date: Y-m-d H:M:S.f - - :code 200 OK: Instance successfully rebuilt - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If instance does not exist - - Example input: - - .. literalinclude:: ../api_examples/input/rebuild_instance-body.json - :language: json - """ body = jsonutils.loads(flask.request.data) LOG.info("Rebuilding instance with id %s with data %s", instance_id, body) instance_ctl.rebuild_instance( @@ -237,21 +162,6 @@ def rebuild_instance(instance_id): @authenticated @to_json def list_instances(project_id): - """List instances for a tenant. - - :arg uuid project_id: Tenant Uuid - :arg datetime start: Y-m-d H:M:S.f - :arg datetime end: Y-m-d H:M:S.f - - :code 200 OK: instance list exists - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If tenant does not exist. - - Example output: - - .. literalinclude:: ../api_examples/output/instances.json - :language: json - """ start, end = get_period() LOG.info("Listing instances between %s and %s", start, end) return instance_ctl.list_instances(project_id, start, end) @@ -261,25 +171,6 @@ def list_instances(project_id): @authenticated @to_json def create_volume(project_id): - """Create a volume for a tenant. - - :arg uuid project_id: Tenant Uuid - :arg uuid volume_id: The Volume Uuid - :arg datetime start: Y-m-d H:M:S.f - :arg uuid volume_type: The Volume Type Uuid - :arg str size: The Volume Size - :arg str volume_name: The Volume Name - :arg uuid attached_to: The Instance Uuid the volume is attached to - - :code 201 Created: Volume successfully created - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If tenant does not exist. - - Example input: - - .. literalinclude:: ../api_examples/input/create_volume-body.json - :language: json - """ volume = jsonutils.loads(flask.request.data) LOG.info("Creating volume for tenant %s with data %s", project_id, volume) volume_ctl.create_volume( @@ -299,15 +190,6 @@ def create_volume(project_id): @authenticated @to_json def delete_volume(volume_id): - """Delete the volume. - - :arg uuid volume_id: Volume Uuid - :arg datetime date: Y-m-d H:M:S.f - - :code 202 Accepted: Volume successfully deleted - :code 400 Bad Request: If data invalid or missing - :code 404 Not Found: If volume does not exist. - """ data = jsonutils.loads(flask.request.data) LOG.info("Deleting volume with id %s with data %s", volume_id, data) volume_ctl.delete_volume( @@ -322,21 +204,6 @@ def delete_volume(volume_id): @authenticated @to_json def resize_volume(volume_id): - """Re-size a volume when the volume size was changed in OpenStack. - - :arg uuid volume_id: Volume Uuid - :arg str size: The size of the volume - :arg datetime date: Y-m-d H:M:S.f - - :code 200 OK: Volume successfully re-sized - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If volume does not exist. - - Example input: - - .. literalinclude:: ../api_examples/input/resize_volume-body.json - :language: json - """ volume = jsonutils.loads(flask.request.data) LOG.info("Resizing volume with id %s with data %s", volume_id, volume) volume_ctl.resize_volume( @@ -352,21 +219,6 @@ def resize_volume(volume_id): @authenticated @to_json def attach_volume(volume_id): - """Update the attachments for a volume when the volume attachments have been changed in OpenStack. - - :arg uuid volume_id: Volume Uuid - :arg datetime date: Y-m-d H:M:S.f - :arg dict attachments: The volume attachments - - :code 200 OK: Volume successfully attached - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If volume does not exist. - - Example input: - - .. literalinclude:: ../api_examples/input/attach_volume-body.json - :language: json - """ volume = jsonutils.loads(flask.request.data) LOG.info("Attaching volume with id %s with data %s", volume_id, volume) volume_ctl.attach_volume( @@ -382,19 +234,6 @@ def attach_volume(volume_id): @authenticated @to_json def detach_volume(volume_id): - """Detaches a volume when the volume is detached in OpenStack. - - :arg uuid volume_id: Volume Uuid - - :code 200 OK: Volume successfully detached - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If volume does not exist. - - Example input: - - .. literalinclude:: ../api_examples/input/detach_volume-body.json - :language: json - """ volume = jsonutils.loads(flask.request.data) LOG.info("Detaching volume with id %s with data %s", volume_id, volume) volume_ctl.detach_volume( @@ -410,21 +249,6 @@ def detach_volume(volume_id): @authenticated @to_json def list_volumes(project_id): - """List volumes for a tenant. - - :arg uuid project_id: Tenant Uuid - :arg datetime start: Y-m-d H:M:S.f - :arg datetime end: Y-m-d H:M:S.f - - :code 200 OK: volume list exists - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If tenant does not exist. - - Example output: - - .. literalinclude:: ../api_examples/output/volumes.json - :language: json - """ start, end = get_period() LOG.info("Listing volumes between %s and %s", start, end) return volume_ctl.list_volumes(project_id, start, end) @@ -434,22 +258,6 @@ def list_volumes(project_id): @authenticated @to_json def list_entity(project_id): - """List instances and volumes for a tenant. - - :arg uuid project_id: Tenant Uuid - :arg datetime start: Y-m-d H:M:S.f - :arg datetime end: Y-m-d H:M:S.f - - :code 200 OK: instances and volumes list exists - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If tenant does not exist. - - - Example output: - - .. literalinclude:: ../api_examples/output/entities.json - :language: json - """ start, end = get_period() LOG.info("Listing entities between %s and %s", start, end) return entity_ctl.list_entities(project_id, start, end) @@ -459,26 +267,6 @@ def list_entity(project_id): @authenticated @to_json def update_instance_entity(instance_id): - """Update an instance entity. - - :arg uuid instance_id: Instance Uuid - :arg datetime start: Y-m-d H:M:S.f - :arg datetime end: Y-m-d H:M:S.f - - :code 200 OK: Entity successfully updated - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If instance does not exist. - - Example input: - - .. literalinclude:: ../api_examples/input/update_instance_entity-body.json - :language: json - - Example output: - - .. literalinclude:: ../api_examples/output/update_instance_entity.json - :language: json - """ data = jsonutils.loads(flask.request.data) LOG.info("Updating instance entity with id %s with data %s", instance_id, data) if 'start' in flask.request.args: @@ -492,13 +280,6 @@ def update_instance_entity(instance_id): @api.route("/entity/", methods=["HEAD"]) @authenticated def entity_exists(entity_id): - """Verify that an entity exists. - - :arg uuid entity_id: Entity Uuid - - :code 200 OK: if the entity exists - :code 404 Not Found: if the entity does not exist - """ LOG.info("Does entity with id %s exists", entity_id) response = flask.Response('', 404) if entity_ctl.entity_exists(entity_id=entity_id): @@ -510,18 +291,6 @@ def entity_exists(entity_id): @authenticated @to_json def get_entity(entity_id): - """Get an entity. - - :arg uuid entity_id: Entity Uuid - - :code 200 OK: Entity exists - :code 404 Not Found: If the entity does not exist - - Example output: - - .. literalinclude:: ../api_examples/output/entity.json - :language: json - """ return entity_ctl.get_all_entities_by_id(entity_id) @@ -529,15 +298,6 @@ def get_entity(entity_id): @authenticated @to_json def list_volume_types(): - """List volume types. - - :code 200 OK: Volume types exist - - Example output: - - .. literalinclude:: ../api_examples/output/volume_types.json - :language: json - """ LOG.info("Listing volumes types") return volume_type_ctl.list_volume_types() @@ -546,19 +306,6 @@ def list_volume_types(): @authenticated @to_json def get_volume_type(volume_type_id): - """Get a volume type. - - :arg uuid volume_type_id: Volume Type Uuid - - :code 200 OK: Volume type exists - :code 400 Bad Request: If request data has an invalid or missing field - :code 404 Not Found: If the volume type does not exist - - Example output: - - .. literalinclude:: ../api_examples/output/volume_type.json - :language: json - """ LOG.info("Get volumes type for id %s", volume_type_id) return volume_type_ctl.get_volume_type(volume_type_id) @@ -567,19 +314,6 @@ def get_volume_type(volume_type_id): @authenticated @to_json def create_volume_type(): - """Create a volume type. - - :arg str type_id: The Volume Type id - :arg str type_name: The Volume Type name - - :code 201 Created: Volume successfully created - :code 400 Bad Request: If request data has an invalid or missing field - - Example input: - - .. literalinclude:: ../api_examples/input/create_volume_type-body.json - :language: json - """ volume_type = jsonutils.loads(flask.request.data) LOG.info("Creating volume type with data '%s'", volume_type) volume_type_ctl.create_volume_type( @@ -593,13 +327,6 @@ def create_volume_type(): @authenticated @to_json def delete_volume_type(volume_type_id): - """Delete the volume type. - - :arg uuid type_id: Volume Type Uuid - - :code 202 Accepted: Volume successfully deleted - :code 404 Not Found: If volume type does not exist. - """ LOG.info("Deleting volume type with id '%s'", volume_type_id) volume_type_ctl.delete_volume_type(volume_type_id) return flask.Response(status=202) diff --git a/doc/api_examples/input/resize_instance-body.json b/doc/api_examples/input/resize_instance-body.json deleted file mode 100644 index a24fefa..0000000 --- a/doc/api_examples/input/resize_instance-body.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "flavor": "my_new_flavor", - "date": "2016-11-24 17:25:05+00:00" -} \ No newline at end of file diff --git a/doc/api_examples/input/update_instance_entity-body.json b/doc/api_examples/input/update_instance_entity-body.json deleted file mode 100644 index 4ea34d1..0000000 --- a/doc/api_examples/input/update_instance_entity-body.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "start_date": "2016-11-24T17:25:05.00Z", - "end_date": "2016-11-24T17:35:05.00Z" -} \ No newline at end of file diff --git a/doc/api_examples/input/attach_volume-body.json b/doc/source/api_examples/input/attach_volume-body.json similarity index 100% rename from doc/api_examples/input/attach_volume-body.json rename to doc/source/api_examples/input/attach_volume-body.json diff --git a/doc/api_examples/input/create_instance-body.json b/doc/source/api_examples/input/create_instance-body.json similarity index 82% rename from doc/api_examples/input/create_instance-body.json rename to doc/source/api_examples/input/create_instance-body.json index 11375cb..79c2e94 100644 --- a/doc/api_examples/input/create_instance-body.json +++ b/doc/source/api_examples/input/create_instance-body.json @@ -2,7 +2,7 @@ "project_id": "ce2d9f6bde52447a831887aac8b7ec98", "id": "460bb2b6-28d6-42c0-9da4-4288dc3025cc", "created_at": "2016-11-24 15:15:05+00:00", - "flavor": "my_flavor_name", + "flavor": "946d7b8f-b20a-4a1d-bf43-567fa27db614", "os_type": "linux", "os_version": "7", "os_distro": "centos", diff --git a/doc/api_examples/input/create_volume-body.json b/doc/source/api_examples/input/create_volume-body.json similarity index 100% rename from doc/api_examples/input/create_volume-body.json rename to doc/source/api_examples/input/create_volume-body.json diff --git a/doc/api_examples/input/create_volume_type-body.json b/doc/source/api_examples/input/create_volume_type-body.json similarity index 100% rename from doc/api_examples/input/create_volume_type-body.json rename to doc/source/api_examples/input/create_volume_type-body.json diff --git a/doc/api_examples/input/delete_instance-body.json b/doc/source/api_examples/input/delete_instance-body.json similarity index 100% rename from doc/api_examples/input/delete_instance-body.json rename to doc/source/api_examples/input/delete_instance-body.json diff --git a/doc/api_examples/input/delete_volume-body.json b/doc/source/api_examples/input/delete_volume-body.json similarity index 100% rename from doc/api_examples/input/delete_volume-body.json rename to doc/source/api_examples/input/delete_volume-body.json diff --git a/doc/api_examples/input/detach_volume-body.json b/doc/source/api_examples/input/detach_volume-body.json similarity index 100% rename from doc/api_examples/input/detach_volume-body.json rename to doc/source/api_examples/input/detach_volume-body.json diff --git a/doc/api_examples/input/rebuild_instance-body.json b/doc/source/api_examples/input/rebuild_instance-body.json similarity index 100% rename from doc/api_examples/input/rebuild_instance-body.json rename to doc/source/api_examples/input/rebuild_instance-body.json diff --git a/doc/source/api_examples/input/resize_instance-body.json b/doc/source/api_examples/input/resize_instance-body.json new file mode 100644 index 0000000..1875aec --- /dev/null +++ b/doc/source/api_examples/input/resize_instance-body.json @@ -0,0 +1,4 @@ +{ + "flavor": "173a54a0-fd55-423e-8084-1ef66d1b428a", + "date": "2016-11-24 17:25:05+00:00" +} \ No newline at end of file diff --git a/doc/api_examples/input/resize_volume-body.json b/doc/source/api_examples/input/resize_volume-body.json similarity index 100% rename from doc/api_examples/input/resize_volume-body.json rename to doc/source/api_examples/input/resize_volume-body.json diff --git a/doc/source/api_examples/input/update_instance_entity-body.json b/doc/source/api_examples/input/update_instance_entity-body.json new file mode 100644 index 0000000..e1099e7 --- /dev/null +++ b/doc/source/api_examples/input/update_instance_entity-body.json @@ -0,0 +1,4 @@ +{ + "start": "2016-11-24T17:25:05.00Z", + "end": "2016-11-24T17:35:05.00Z" +} \ No newline at end of file diff --git a/doc/api_examples/output/entities.json b/doc/source/api_examples/output/entities.json similarity index 100% rename from doc/api_examples/output/entities.json rename to doc/source/api_examples/output/entities.json diff --git a/doc/api_examples/output/entity.json b/doc/source/api_examples/output/entity.json similarity index 100% rename from doc/api_examples/output/entity.json rename to doc/source/api_examples/output/entity.json diff --git a/doc/api_examples/output/info.json b/doc/source/api_examples/output/info.json similarity index 100% rename from doc/api_examples/output/info.json rename to doc/source/api_examples/output/info.json diff --git a/doc/api_examples/output/instances.json b/doc/source/api_examples/output/instances.json similarity index 88% rename from doc/api_examples/output/instances.json rename to doc/source/api_examples/output/instances.json index b8bf263..0be2f59 100644 --- a/doc/api_examples/output/instances.json +++ b/doc/source/api_examples/output/instances.json @@ -6,7 +6,7 @@ "last_event": "2016-11-24 15:14:08+00:00", "entity_type": "instance", "start": "2016-11-24 15:14:08+00:00", - "flavor": "my_flavor_name", + "flavor": "173a54a0-fd55-423e-8084-1ef66d1b428a", "project_id": "ce2d9f6bde52447a831887aac8b7ec98", "os": { "os_type": "linux", diff --git a/doc/api_examples/output/update_instance_entity.json b/doc/source/api_examples/output/update_instance_entity.json similarity index 100% rename from doc/api_examples/output/update_instance_entity.json rename to doc/source/api_examples/output/update_instance_entity.json diff --git a/doc/api_examples/output/volume_type.json b/doc/source/api_examples/output/volume_type.json similarity index 100% rename from doc/api_examples/output/volume_type.json rename to doc/source/api_examples/output/volume_type.json diff --git a/doc/api_examples/output/volume_types.json b/doc/source/api_examples/output/volume_types.json similarity index 100% rename from doc/api_examples/output/volume_types.json rename to doc/source/api_examples/output/volume_types.json diff --git a/doc/api_examples/output/volumes.json b/doc/source/api_examples/output/volumes.json similarity index 100% rename from doc/api_examples/output/volumes.json rename to doc/source/api_examples/output/volumes.json diff --git a/doc/source/conf.py b/doc/source/conf.py index 822b6d7..dddba4f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,9 +21,7 @@ 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. -extensions = [ - 'sphinxcontrib.autohttp.flask' -] +extensions = [] # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. diff --git a/doc/source/index.rst b/doc/source/index.rst index 34bc953..dd31a6d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -247,6 +247,709 @@ Almanach will process those events: API documentation ----------------- -.. autoflask:: almanach.api.main:app - :undoc-static: - :include-empty-docstring: +:code:`GET /volume_types` + + List volume types. + + Status Codes: + + - **200 OK** Volume types exist + + Example output: + + .. literalinclude:: api_examples/output/volume_types.json + :language: json + +:code:`GET /volume_type/` + + Get a volume type. + + Status Codes: + + - **200 OK** Volume type exist + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the volume type does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - volume_type_id + - path + - uuid + - The Volume Type Uuid + + + Example output: + + .. literalinclude:: api_examples/output/volume_type.json + :language: json + +:code:`POST /volume_type` + + Create a volume type. + + Status Codes: + + - **201 Created** Volume type successfully created + - **400 Bad Request** If request data has an invalid or missing field + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - type_id + - body + - uuid + - The Volume Type Uuid + * - type_name + - body + - string + - The Volume Type Name + + Example input: + + .. literalinclude:: api_examples/input/create_volume_type-body.json + :language: json + +:code:`DELETE /volume_type/` + + Delete a volume type. + + Status Codes: + + - **202 Accepted** Volume type successfully deleted + - **404 Not Found** If the volume type does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - volume_type_id + - path + - uuid + - The Volume Type Uuid + +:code:`GET /info` + + Display information about the current version and entity counts. + + Status Codes: + + - **200 OK** Service is available + + Example output: + + .. literalinclude:: api_examples/output/info.json + :language: json + +:code:`POST /project//instance` + + Create an instance. + + Status Codes: + + - **201 Created** Instance successfully created + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If tenant does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - project_id + - body + - uuid + - The Tenant Uuid + * - id + - body + - uuid + - The instance Uuid + * - created_at + - body + - datetime + - Y-m-d H:M:S.f + * - flavor + - body + - uuid + - The flavor Uuid + * - os_type + - body + - string + - The OS type + * - os_distro + - body + - string + - The OS distro + * - os_version + - body + - string + - The OS version + * - name + - body + - string + - The instance name + + Example input: + + .. literalinclude:: api_examples/input/create_instance-body.json + :language: json + +:code:`DELETE /instance/` + + Delete an instance. + + Status Codes: + + - **202 Accepted** Instance successfully deleted + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the instance does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - instance_id + - path + - uuid + - The instance Uuid + * - date + - body + - datetime + - Y-m-d H:M:S.f + + Example input: + + .. literalinclude:: api_examples/input/delete_instance-body.json + :language: json + +:code:`PUT /instance//resize` + + Re-size an instance. + + Status Codes: + + - **202 Accepted** Instance successfully re-sized + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the instance does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - instance_id + - path + - uuid + - The instance Uuid + * - date + - body + - datetime + - Y-m-d H:M:S.f + * - flavor + - body + - uuid + - The flavor Uuid + + Example input: + + .. literalinclude:: api_examples/input/resize_instance-body.json + :language: json + +:code:`PUT /instance//rebuild` + + Rebuild an instance. + + Status Codes: + + - **202 Accepted** Instance successfully rebuilt + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the instance does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - instance_id + - path + - uuid + - The instance Uuid + * - rebuild_date + - body + - datetime + - Y-m-d H:M:S.f + * - os_type + - body + - string + - The OS type + * - os_distro + - body + - string + - The OS distro + * - os_version + - body + - string + - The OS version + + Example input: + + .. literalinclude:: api_examples/input/rebuild_instance-body.json + :language: json + +:code:`GET /project//instances` + + List instances for a tenant. + + Status Codes: + + - **200 OK** Instances exist + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the tenant does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - project_id + - path + - uuid + - The Tenant Uuid + * - start + - path + - datetime + - Y-m-d H:M:S.f + * - end + - path + - datetime + - Y-m-d H:M:S.f + + Example output: + + .. literalinclude:: api_examples/output/instances.json + :language: json + +:code:`POST /project//volume` + + Create a volume. + + Status Codes: + + - **201 Created** Volume successfully created + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If tenant does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - project_id + - body + - uuid + - The Tenant Uuid + * - volume_id + - body + - uuid + - The volume Uuid + * - start + - body + - datetime + - Y-m-d H:M:S.f + * - volume_type + - body + - uuid + - The volume type Uuid + * - size + - body + - string + - The volume size + * - volume_name + - body + - string + - The volume name + * - attached_to + - body + - uuid + - The instance uuid the volume is attached to + + Example input: + + .. literalinclude:: api_examples/input/create_volume-body.json + :language: json + +:code:`DELETE /volume/` + + Delete a volume. + + Status Codes: + + - **202 Accepted** Volume successfully deleted + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the volume does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - volume_id + - path + - uuid + - The volume Uuid + * - date + - body + - datetime + - Y-m-d H:M:S.f + + Example input: + + .. literalinclude:: api_examples/input/delete_volume-body.json + :language: json + +:code:`PUT /volume//resize` + + Re-size a volume. + + Status Codes: + + - **202 Accepted** Volume successfully re-sized + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the volume does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - volume_id + - path + - uuid + - The volume Uuid + * - date + - body + - datetime + - Y-m-d H:M:S.f + * - size + - body + - string + - The volume size + + Example input: + + .. literalinclude:: api_examples/input/resize_volume-body.json + :language: json + +:code:`PUT /volume//attach` + + Update the attachments for a volume. + + Status Codes: + + - **202 Accepted** Volume successfully attached + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the volume does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - volume_id + - path + - uuid + - The volume Uuid + * - date + - body + - datetime + - Y-m-d H:M:S.f + * - attachments + - body + - dict + - The volume attachments + + Example input: + + .. literalinclude:: api_examples/input/attach_volume-body.json + :language: json + +:code:`PUT /volume//detach` + + Detach a volume. + + Status Codes: + + - **202 Accepted** Volume successfully detached + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the volume does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - volume_id + - path + - uuid + - The volume Uuid + * - date + - body + - datetime + - Y-m-d H:M:S.f + * - attachments + - body + - dict + - The volume attachments + + Example input: + + .. literalinclude:: api_examples/input/detach_volume-body.json + :language: json + +:code:`GET /project//volumes` + + List volumes for a tenant. + + Status Codes: + + - **200 OK** Volumes exist + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the tenant does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - project_id + - path + - uuid + - The Tenant Uuid + * - start + - path + - datetime + - Y-m-d H:M:S.f + * - end + - path + - datetime + - Y-m-d H:M:S.f + + Example output: + + .. literalinclude:: api_examples/output/volumes.json + :language: json + +:code:`GET /project//entities` + + List entities for a tenant. + + Status Codes: + + - **200 OK** Entities exist + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the tenant does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - project_id + - path + - uuid + - The Tenant Uuid + * - start + - path + - datetime + - Y-m-d H:M:S.f + * - end + - path + - datetime + - Y-m-d H:M:S.f + + Example output: + + .. literalinclude:: api_examples/output/entities.json + :language: json + +:code:`PUT /entity/instance/` + + Update an instance. + + Status Codes: + + - **202 Accepted** Instance successfully updated + - **400 Bad Request** If request data has an invalid or missing field + - **404 Not Found** If the instance does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - instance_id + - path + - uuid + - The instance Uuid + * - start + - body + - datetime + - Y-m-d H:M:S.f + * - end + - body + - datetime + - Y-m-d H:M:S.f + + Example input: + + .. literalinclude:: api_examples/input/update_instance_entity-body.json + :language: json + + Example output: + + .. literalinclude:: api_examples/output/update_instance_entity.json + :language: json + +:code:`HEAD /entity/` + + Verify that an entity exists. + + Status Codes: + + - **200 OK** Entity exists + - **404 Not Found** If the entity does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - entity_id + - path + - uuid + - The Entity Uuid + + Example output: + + .. literalinclude:: api_examples/output/entity.json + :language: json + +:code:`GET /entity/` + + Get an entity. + + Status Codes: + + - **200 OK** If the entity exists + - **404 Not Found** If the entity does not exist + + Request: + + .. list-table:: + :widths: 22 8 15 55 + :header-rows: 1 + + * - Name + - In + - Type + - Description + * - entity_id + - path + - uuid + - The Entity Uuid + + Example output: + + .. literalinclude:: api_examples/output/entity.json + :language: json diff --git a/test-requirements.txt b/test-requirements.txt index d257e6c..e461912 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -2,7 +2,6 @@ mongomock==2.0.0 nose # LGPL setuptools>=16.0,!=24.0.0 # PSF/ZPL sphinx>=1.2.1,!=1.3b1,<1.3 # BSD -sphinxcontrib-httpdomain # BSD flake8>=2.5.4,<2.6.0 # MIT hacking<0.12,>=0.11.0 # Apache-2.0 testtools>=1.4.0 # MIT