78c4ce8ac8
This repository is hosted on opendev.org's gitea server, and doesn't get mirrored to github currently (we may add mirroring in the future). We can swap a bunch of URLs that assume the content is on github and older infra cgit servers with correct URLs. Meetings have moved from IRC to MeetPad, fix the corresponding details in the README. Also use this commit to strip trailing whitespaces across the repository. Change-Id: Ica0a7ba08d9c437f94fbc9ab282bd929f01df8ff
282 lines
7.2 KiB
ReStructuredText
Executable File
282 lines
7.2 KiB
ReStructuredText
Executable File
======================
|
|
Defcore Guideline API
|
|
======================
|
|
|
|
This spec defines the REST APIs needed to support the retrieval of DefCore
|
|
Guideline files and the test lists included in these files.
|
|
|
|
|
|
Problem description
|
|
===================
|
|
|
|
The DefCore Guideline files contain many different types of test lists such as
|
|
required test lists, advisory test lists, etc. Very often, these lists are used
|
|
by RefStack users to test only the tests that they are interested in.
|
|
For each Guideline file, there is a corresponding directory which holds files
|
|
that contain the required or flagged tests (see example [1]). Since the test
|
|
lists in these files can change from time to time due to test name changes [2]
|
|
or addition of flagged tests [3], it is useful for RefStack to provide
|
|
REST APIs so that users can dynamically retrieve the test lists with the latest
|
|
updates in the Guideline files as needed.
|
|
|
|
[1] https://opendev.org/osf/interop/src/branch/master/2016.01/
|
|
[2] https://review.opendev.org/290689/
|
|
[3] https://review.opendev.org/215263/
|
|
|
|
Proposed change
|
|
===============
|
|
|
|
RefStack to provide the REST APIs as described in the "REST API Impact" section
|
|
to retrieve the Guideline files and the test lists included in these files.
|
|
|
|
|
|
Alternatives
|
|
------------
|
|
|
|
Users to continue using the required and flagged test list files in the DefCore
|
|
repository.
|
|
|
|
Data model impact
|
|
-----------------
|
|
|
|
None
|
|
|
|
REST API impact
|
|
---------------
|
|
|
|
The following REST APIs will be added to RefStack.
|
|
|
|
**List DefCore Guideline files**
|
|
|
|
* Description:
|
|
|
|
List the names of the DefCore Guideline files
|
|
|
|
* Method type: GET
|
|
|
|
* URI: v1/guidelines/
|
|
|
|
* Normal Response Codes:
|
|
|
|
* OK (200)
|
|
|
|
* Error Response Codes:
|
|
|
|
* Bad Request (400)
|
|
|
|
* Request parameters:
|
|
|
|
N/A
|
|
|
|
* JSON schema definition for the body data:
|
|
|
|
N/A
|
|
|
|
* Schema definition for the response data:
|
|
|
|
.. parsed-literal::
|
|
[
|
|
"2015.03.json",
|
|
"2015.04.json",
|
|
...
|
|
]
|
|
|
|
|
|
**Show Guideline file details**
|
|
|
|
* Description:
|
|
|
|
This API will be used to retrieve the content of a
|
|
DefCore Guideline file.
|
|
|
|
* Method type: GET
|
|
|
|
* URI: v1/guidelines/{name}
|
|
|
|
* Normal Response Codes:
|
|
|
|
* OK (200)
|
|
|
|
* Error Response Codes:
|
|
|
|
* Bad Request (400)
|
|
* Not found (404)
|
|
|
|
* Request parameters:
|
|
|
|
+---------------+-------+--------------+-----------------------------------+
|
|
| Parameter | Style | Type | Description |
|
|
+===============+=======+==============+===================================+
|
|
| name | URI | xsd:string | The name of the Guideline file |
|
|
| | | | such as "2015.04". |
|
|
+---------------+-------+--------------+-----------------------------------+
|
|
|
|
* JSON schema definition for the body data:
|
|
|
|
N/A
|
|
|
|
* JSON schema definition for the response data:
|
|
|
|
See DefCore Guideline JSON schema
|
|
https://opendev.org/osf/interop/src/master/doc/source/schema
|
|
|
|
|
|
**List tests**
|
|
|
|
* Description:
|
|
|
|
This API will be used to list the tests included in the Guideline. By default,
|
|
this API will return all the tests included in the required, advisory,
|
|
deprecated and removed categories.
|
|
|
|
* Method type: GET
|
|
|
|
* URI: v1/guidelines/{name}/tests
|
|
|
|
* Normal Response Codes:
|
|
|
|
* OK (200)
|
|
|
|
* Error Response Codes:
|
|
|
|
* Bad Request (400)
|
|
* Not found (404)
|
|
|
|
* Request parameters:
|
|
|
|
+---------------+-------+--------------+-----------------------------------+
|
|
| Parameter | Style | Type | Description |
|
|
+===============+=======+==============+===================================+
|
|
| type | query | xsd:string | Type can be a comma separated list|
|
|
| (optional) | | | of required, advisory, deprecated |
|
|
| | | | and removed. Default is to |
|
|
| | | | retrieve test list of all types. |
|
|
+---------------+-------+--------------+-----------------------------------+
|
|
| alias | query | xsd:string | Set alias=true (default) to |
|
|
| (optional) | | | include alias test names in the |
|
|
| | | | response test list. |
|
|
| | | | alias=false will exclude the alias|
|
|
| | | | test names. |
|
|
+---------------+-------+--------------+-----------------------------------+
|
|
| flag | query | xsd:string | Set flag=true (default) to include|
|
|
| (optional) | | | flagged test names in the |
|
|
| | | | response test list. |
|
|
| | | | flag=false will not include |
|
|
| | | | flagged tests. |
|
|
+---------------+-------+--------------+-----------------------------------+
|
|
| target | query | xsd:string | Use this parameter to retrieve the|
|
|
| (optional) | | | test lists for a target program. |
|
|
| | | | Current valid values include the |
|
|
| | | | following: |
|
|
| | | | |
|
|
| | | | - platform (default) |
|
|
| | | | - compute |
|
|
| | | | - object-storage |
|
|
+---------------+-------+--------------+-----------------------------------+
|
|
|
|
**Note**
|
|
|
|
More information about OpenStack Target Programs can be found at
|
|
http://www.openstack.org/brand/interop/ .
|
|
|
|
**Examples**
|
|
|
|
* Get the required test list including alias and flagged tests.
|
|
|
|
`v1/guidelines/2016.01/tests?type=required`
|
|
|
|
* Get the required test list including alias but excluding flagged tests.
|
|
|
|
`v1/guidelines/2016.01/tests?type=required&flag=false`
|
|
|
|
* Get the required and advisory tests for the OpenStack Powered Compute
|
|
program, including alias but excluding flagged tests
|
|
|
|
`v1/guidelines/2016.01/tests?type=required,advisory&flag=false&target=compute`
|
|
|
|
|
|
* JSON schema definition for the body data:
|
|
|
|
N/A
|
|
|
|
* Schema definition for the response data:
|
|
|
|
The response is a straight list of tests so that users can immediately use the file
|
|
as-is for testing with refstack-client.
|
|
|
|
.. parsed-literal::
|
|
tempest.api.compute.images.test_list_images.ListImagesTestJSON.test_get_image[id-490d0898-e12a-463f-aef0-c50156b9f789]
|
|
tempest.api.compute.images.test_list_images.ListImagesTestJSON.test_list_images[id-fd51b7f4-d4a3-4331-9885-866658112a6f]
|
|
....
|
|
|
|
Security impact
|
|
---------------
|
|
|
|
None.
|
|
|
|
Notifications impact
|
|
--------------------
|
|
|
|
None.
|
|
|
|
Other end user impact
|
|
---------------------
|
|
|
|
None
|
|
|
|
Performance Impact
|
|
------------------
|
|
|
|
None
|
|
|
|
Other deployer impact
|
|
---------------------
|
|
|
|
None
|
|
|
|
Developer impact
|
|
----------------
|
|
|
|
None
|
|
|
|
Implementation
|
|
==============
|
|
|
|
Assignee(s)
|
|
-----------
|
|
|
|
Primary assignee:
|
|
Paul Van Eck
|
|
|
|
Other contributors:
|
|
TBD
|
|
|
|
Work Items
|
|
----------
|
|
|
|
* Create the REST APIs.
|
|
|
|
|
|
Dependencies
|
|
============
|
|
|
|
None
|
|
|
|
|
|
Testing
|
|
=======
|
|
|
|
None
|
|
|
|
|
|
Documentation Impact
|
|
====================
|
|
|
|
None
|
|
|
|
|
|
References
|
|
==========
|
|
|
|
None
|