Skip to content

Commit

Permalink
Describe query parameters in OpenAPI schema
Browse files Browse the repository at this point in the history 
Remove PEP8 E251/E252 (unexpected spaces around keyword / parameter
equals) from lint warnings.

Update `page_page` to `page_number` according to
Materials-Consortia/OPTIMADE#187.

Due to pydantic:
https://pydantic-docs.helpmanual.io/usage/schema/#unenforced-field-constraints
the `ge` parameter cannot be used together with a non-standard type,
e.g. NonnegativeInt. Instead the OpenAPI parameter is set directly, here
`minimum`.

Regular expressions are added for `response_fields` and `sort` based on
the regular expressions provided for an `identifier` in the OPTiMaDe
spec.
  • Loading branch information
@CasperWA
CasperWA committed Feb 6, 2020
1 parent 4e5a208 commit 7f1d660
Show file tree
Hide file tree
Showing 5 changed files with 217 additions and 37 deletions.
30 changes: 26 additions & 4 deletions openapi/index_openapi.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,119 +44,141 @@
"operationId": "get_links_index_optimade_v0_links_get",
"parameters": [
{
"description": "See [the full and latest OPTiMaDe spec](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst) for filter query syntax.\n\nExample: `chemical_formula = \"Al\" OR (prototype_formula = \"AB\" AND elements HAS Si, Al, O)`.\n",
"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTiMaDe spec](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst).",
"required": false,
"schema": {
"title": "Filter",
"type": "string",
"description": "See [the full and latest OPTiMaDe spec](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst) for filter query syntax.\n\nExample: `chemical_formula = \"Al\" OR (prototype_formula = \"AB\" AND elements HAS Si, Al, O)`.\n",
"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTiMaDe spec](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst).",
"default": ""
},
"name": "filter",
"in": "query"
},
{
"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/optimade/v0.9/structures?response_format=xml",
"required": false,
"schema": {
"title": "Response Format",
"type": "string",
"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/optimade/v0.9/structures?response_format=xml",
"default": "json"
},
"name": "response_format",
"in": "query"
},
{
"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/optimade/v0.9/structures?email_address=user@example.com",
"required": false,
"schema": {
"title": "Email Address",
"type": "string",
"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/optimade/v0.9/structures?email_address=user@example.com",
"format": "email",
"default": ""
},
"name": "email_address",
"in": "query"
},
{
"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/optimade/v0.9/structures?response_fields=last_modified,nsites",
"required": false,
"schema": {
"title": "Response Fields",
"pattern": "[a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*",
"type": "string",
"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/optimade/v0.9/structures?response_fields=last_modified,nsites",
"default": ""
},
"name": "response_fields",
"in": "query"
},
{
"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#entry-listing-info-endpoints).",
"required": false,
"schema": {
"title": "Sort",
"pattern": "[a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*",
"type": "string",
"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#entry-listing-info-endpoints).",
"default": ""
},
"name": "sort",
"in": "query"
},
{
"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",
"required": false,
"schema": {
"title": "Page Limit",
"minimum": 0.0,
"type": "integer",
"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",
"default": 20
},
"name": "page_limit",
"in": "query"
},
{
"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",
"required": false,
"schema": {
"title": "Page Offset",
"minimum": 0.0,
"type": "integer",
"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",
"default": 0
},
"name": "page_offset",
"in": "query"
},
{
"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",
"required": false,
"schema": {
"title": "Page Page",
"title": "Page Number",
"minimum": 0.0,
"type": "integer",
"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",
"default": 0
},
"name": "page_page",
"name": "page_number",
"in": "query"
},
{
"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",
"required": false,
"schema": {
"title": "Page Cursor",
"minimum": 0.0,
"type": "integer",
"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",
"default": 0
},
"name": "page_cursor",
"in": "query"
},
{
"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",
"required": false,
"schema": {
"title": "Page Above",
"minimum": 0.0,
"type": "integer",
"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",
"default": 0
},
"name": "page_above",
"in": "query"
},
{
"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",
"required": false,
"schema": {
"title": "Page Below",
"minimum": 0.0,
"type": "integer",
"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",
"default": 0
},
"name": "page_below",
Expand Down

0 comments on commit 7f1d660

Please sign in to comment.