Skip to content

Commit

Permalink
Merge pull request Materials-Consortia#166 from CasperWA/close_164_qu…
Browse files Browse the repository at this point in the history 
…ery_param_descriptions

Describe query parameters in OpenAPI schema.

Remove custom constrained types and replace with
clever use of standard types as well as pydantic's
`FieldInfo` parameters that both do validation and schema
generation.

Further tests should be added that the validation is correct
in edge cases, as well as further validation required by the
OPTiMaDe spec.
  • Loading branch information
@CasperWA
CasperWA authored Feb 6, 2020
2 parents 80e2dcc + d09595b commit 7de415a
Show file tree
Hide file tree
Showing 14 changed files with 544 additions and 243 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.",
"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.",
"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/[email protected]",
"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/[email protected]",
"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
Loading

0 comments on commit 7de415a

Please sign in to comment.