From cb18b647caa0e72be08ffbdaae2916ab4ac0b114 Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Tue, 25 Apr 2017 16:15:34 +0100 Subject: [PATCH] Add categories to api-ref This patch adds the categories api to api-ref. Change-Id: I08409cd9dbcb550fa413f99e11a3c38a5ba9e2cf Partially-Implements: blueprint murano-api-ref --- api-ref/source/v1/categories.inc | 162 ++++++++++++++++++ api-ref/source/v1/environments.inc | 2 +- api-ref/source/v1/index.rst | 1 + api-ref/source/v1/packages.inc | 14 +- api-ref/source/v1/parameters.yaml | 49 +++++- .../v1/samples/category-create-response.json | 7 + .../v1/samples/category-list-response.json | 18 ++ .../v1/samples/category-show-response.json | 14 ++ 8 files changed, 258 insertions(+), 9 deletions(-) create mode 100644 api-ref/source/v1/categories.inc create mode 100644 api-ref/source/v1/samples/category-create-response.json create mode 100644 api-ref/source/v1/samples/category-list-response.json create mode 100644 api-ref/source/v1/samples/category-show-response.json diff --git a/api-ref/source/v1/categories.inc b/api-ref/source/v1/categories.inc new file mode 100644 index 000000000..112dbf157 --- /dev/null +++ b/api-ref/source/v1/categories.inc @@ -0,0 +1,162 @@ +.. -*- rst -*- + +========== +Categories +========== + +In Murano, applications can belong to a category or multiple categories. +Administrative users can create and delete categories as well as list +available categories and view details for a particular category. + +List categories +=============== + +.. rest_method:: GET /catalog/categories + +Retrieve list of all available categories in the Application Catalog. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - X-Openstack-Request-Id: request_id + - categories: all_categories + - id: category_id + - name: category_name + - updated: updated + - created: created + - package_count: package_count + +Response Example +---------------- + +.. literalinclude:: samples/category-list-response.json + :language: javascript + +Show category details +===================== + +.. rest_method:: GET /catalog/categories/{category_id} + +Show details for a category. + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - category_id: category_id_url + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - X-Openstack-Request-Id: request_id + - id: category_id + - name: category_name + - updated: updated + - created: created + - packages: category_packages + - package_count: package_count + +Response Example +---------------- + +.. literalinclude:: samples/category-show-response.json + :language: javascript + +Create Category +=============== + +.. rest_method:: POST /catalog/categories + +Add a new category to the Application Catalog. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 409 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - name: category_name + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - X-Openstack-Request-Id: request_id + - id: category_id + - name: category_name + - updated: updated + - created: created + - package_count: package_count + +Response Example +---------------- + +.. literalinclude:: samples/category-create-response.json + :language: javascript + +Delete Category +=============== + +.. rest_method:: DELETE /catalog/categories/{category_id} + +Remove an existing category from the Application Catalog. + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - category_id: category_id_url + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 diff --git a/api-ref/source/v1/environments.inc b/api-ref/source/v1/environments.inc index 6e61bc166..079f71bbd 100644 --- a/api-ref/source/v1/environments.inc +++ b/api-ref/source/v1/environments.inc @@ -212,7 +212,7 @@ Response Example Delete environment ================== -.. rest_method:: DELETE /environments/{id}?abandon +.. rest_method:: DELETE /environments/{id} Remove specified Environment. diff --git a/api-ref/source/v1/index.rst b/api-ref/source/v1/index.rst index 01cd702ad..23881ee70 100644 --- a/api-ref/source/v1/index.rst +++ b/api-ref/source/v1/index.rst @@ -6,6 +6,7 @@ OpenStack Application Catalog API v1 .. rest_expand_all:: +.. include:: categories.inc .. include:: environments.inc .. include:: packages.inc .. include:: sessions.inc diff --git a/api-ref/source/v1/packages.inc b/api-ref/source/v1/packages.inc index 2df46d28f..865b5c7bf 100644 --- a/api-ref/source/v1/packages.inc +++ b/api-ref/source/v1/packages.inc @@ -63,7 +63,7 @@ Response Parameters - created: created - enabled: enabled - tags: tags - - categories: categories + - categories: package_categories - owner_id: owner_id Response Example @@ -79,6 +79,10 @@ Upload package Create a package. +.. note:: + Though specifying categories is optional, it is recommended that you + specify at least one. It helps to filter applications in the catalog. + Response Codes -------------- @@ -97,7 +101,7 @@ Request Parameters .. rest_parameters:: parameters.yaml - - categories: categories + - categories: package_categories - is_public: is_public - file: pkg_file @@ -120,7 +124,7 @@ Response Parameters - created: created - enabled: enabled - tags: tags - - categories: categories + - categories: package_categories - owner_id: owner_id Response Example @@ -176,7 +180,7 @@ Response Parameters - created: created - enabled: enabled - tags: tags - - categories: categories + - categories: package_categories - owner_id: owner_id Response Example @@ -239,7 +243,7 @@ Response Parameters - created: created - enabled: enabled - tags: tags - - categories: categories + - categories: package_categories - owner_id: owner_id Response Example diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml index 4e35f1cb1..53921d7cc 100644 --- a/api-ref/source/v1/parameters.yaml +++ b/api-ref/source/v1/parameters.yaml @@ -6,6 +6,8 @@ request_id: in: header required: true type: UUID + +# variables in path abandon: description: | Indicates how to delete environment. @@ -15,6 +17,12 @@ abandon: required: false default: false type: boolean +category_id_url: + description: | + The UUID of the category. + in: path + required: true + type: string env_id_url: description: | The UUID of the environment. @@ -41,6 +49,8 @@ pkg_id_url: in: path required: true type: string + +# variables in query all_tenants: description: | Indicates whether environments from all projects are listed. @@ -141,15 +151,36 @@ search: in: query required: false type: string + +# variables in body +all_categories: + description: | + All categories available in the application catalog. + in: body + required: true + type: array author: description: | The author of the package. in: body required: true type: string -categories: +category_id: description: | - The categories of the package. + The UUID of the category. + in: body + required: true + type: string +category_name: + description: | + The name of the category. + in: body + required: true + type: string +category_packages: + description: | + The list of packages associated with a package. Each package returned + includes its ``id``, ``fully_qualified_name``, and ``name``. in: body required: true type: array @@ -201,7 +232,7 @@ env_id: type: string env_model: description: | - The ``?`` sections of the environment.. + The ``?`` sections of the environment. in: body required: true type: array @@ -273,6 +304,18 @@ owner_id: in: body required: true type: string +package_categories: + description: | + The categories associated with the package. + in: body + required: true + type: array +package_count: + description: | + The number of packages associated with the category. + in: body + required: true + type: integer packages: description: | A list of ``package`` object. diff --git a/api-ref/source/v1/samples/category-create-response.json b/api-ref/source/v1/samples/category-create-response.json new file mode 100644 index 000000000..853e40baa --- /dev/null +++ b/api-ref/source/v1/samples/category-create-response.json @@ -0,0 +1,7 @@ +{ + "id": "ce373a477f211e187a55404a662f968", + "name": "category_name", + "created": "2013-11-30T03:23:42Z", + "updated": "2013-11-30T03:23:44Z", + "package_count": 0 +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/category-list-response.json b/api-ref/source/v1/samples/category-list-response.json new file mode 100644 index 000000000..5eebb8b3c --- /dev/null +++ b/api-ref/source/v1/samples/category-list-response.json @@ -0,0 +1,18 @@ +{ + "categories": [ + { + "id": "0420045dce7445fabae7e5e61fff9e2f", + "updated": "2014-12-26T13:57:04", + "name": "Web", + "created": "2014-12-26T13:57:04", + "package_count": 1 + }, + { + "id": "3dd486b1e26f40ac8f35416b63f52042", + "updated": "2014-12-26T13:57:04", + "name": "Databases", + "created": "2014-12-26T13:57:04", + "package_count": 0 + } + ] +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/category-show-response.json b/api-ref/source/v1/samples/category-show-response.json new file mode 100644 index 000000000..eb69273b4 --- /dev/null +++ b/api-ref/source/v1/samples/category-show-response.json @@ -0,0 +1,14 @@ +{ + "id": "b308f7fa8a2f4a5eb419970c827f4466", + "updated": "2015-01-28T17:00:19", + "packages": [ + { + "fully_qualified_name": "io.murano.apps.ZabbixServer", + "id": "4dfb566e69e6445fbd4aea5099fe95e9", + "name": "Zabbix Server" + } + ], + "name": "Web", + "created": "2015-01-28T17:00:19", + "package_count": 1 +} \ No newline at end of file