diff --git a/openapi/contracts/core-provider.openapi.yaml b/openapi/contracts/core-provider.openapi.yaml index 6dec6e16..84af914c 100644 --- a/openapi/contracts/core-provider.openapi.yaml +++ b/openapi/contracts/core-provider.openapi.yaml @@ -211,6 +211,9 @@ paths: post: summary: Query objects operationId: queryObjects + parameters: + - $ref: '#/components/parameters/PageLimit' + - $ref: '#/components/parameters/PageSkip' requestBody: required: true content: @@ -225,12 +228,20 @@ paths: headers: Link: $ref: '#/components/headers/NextPageLink' + Pagination-Limit: + $ref: '#/components/headers/PaginationLimit' + Pagination-Skip: + $ref: '#/components/headers/PaginationSkip' + Pagination-Limit-Max: + $ref: '#/components/headers/PaginationLimitMax' + Pagination-Skip-Max: + $ref: '#/components/headers/PaginationSkipMax' content: application/json: schema: $ref: '#/components/schemas/GenericArray' '400': - $ref: '#/components/responses/BadRequest' + $ref: '#/components/responses/PageBadRequest' '413': $ref: '#/components/responses/PayloadTooLarge' '415': @@ -239,6 +250,9 @@ paths: post: summary: Search objects by keywords operationId: searchObjects + parameters: + - $ref: '#/components/parameters/PageLimit' + - $ref: '#/components/parameters/PageSkip' requestBody: required: true content: @@ -256,12 +270,20 @@ paths: headers: Link: $ref: '#/components/headers/NextPageLink' + Pagination-Limit: + $ref: '#/components/headers/PaginationLimit' + Pagination-Skip: + $ref: '#/components/headers/PaginationSkip' + Pagination-Limit-Max: + $ref: '#/components/headers/PaginationLimitMax' + Pagination-Skip-Max: + $ref: '#/components/headers/PaginationSkipMax' content: application/json: schema: $ref: '#/components/schemas/GenericArray' '400': - $ref: '#/components/responses/BadRequest' + $ref: '#/components/responses/PageBadRequest' '413': $ref: '#/components/responses/PayloadTooLarge' '415': @@ -270,6 +292,9 @@ paths: post: summary: Search objects by phrase operationId: searchObjectsByPhrase + parameters: + - $ref: '#/components/parameters/PageLimit' + - $ref: '#/components/parameters/PageSkip' requestBody: required: true content: @@ -287,12 +312,20 @@ paths: headers: Link: $ref: '#/components/headers/NextPageLink' + Pagination-Limit: + $ref: '#/components/headers/PaginationLimit' + Pagination-Skip: + $ref: '#/components/headers/PaginationSkip' + Pagination-Limit-Max: + $ref: '#/components/headers/PaginationLimitMax' + Pagination-Skip-Max: + $ref: '#/components/headers/PaginationSkipMax' content: application/json: schema: $ref: '#/components/schemas/GenericArray' '400': - $ref: '#/components/responses/BadRequest' + $ref: '#/components/responses/PageBadRequest' '413': $ref: '#/components/responses/PayloadTooLarge' '415': @@ -705,6 +738,33 @@ components: example: >- ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json", ; rel="next" + PaginationLimit: + description: >- + The 'limit' applied to this page, after any reduction to the maximum. Read it rather than + assuming the requested 'limit' was served. + schema: + type: integer + minimum: 1 + PaginationSkip: + description: >- + The 'skip' applied to this page. + schema: + type: integer + minimum: 0 + PaginationLimitMax: + description: >- + The largest 'limit' served. A larger 'limit' is reduced to it. + schema: + type: integer + minimum: 1 + example: 500 + PaginationSkipMax: + description: >- + The largest 'skip' accepted. A larger 'skip' is a 400. + schema: + type: integer + minimum: 1 + example: 100000 parameters: ObjectId: in: path @@ -726,6 +786,29 @@ components: description: Only expand with Annotations attributed to this creator. schema: type: string + PageLimit: + in: query + name: limit + required: false + description: >- + How many records to serve, as a whole number in plain decimal digits. A 'limit' + larger than 500 is reduced to 500 rather than rejected. + schema: + type: integer + minimum: 1 + default: 100 + PageSkip: + in: query + name: skip + required: false + description: >- + How many records to pass over before the page starts, as a whole number in plain decimal + digits. A 'skip' beyond 100000 is rejected with a 400. + schema: + type: integer + minimum: 0 + maximum: 100000 + default: 0 schemas: GenericObject: type: object @@ -737,6 +820,15 @@ components: responses: BadRequest: description: Bad request — the request body was missing, empty, or otherwise invalid. + PageBadRequest: + description: >- + The request body was malformed. It could also mean the 'limit' or 'skip' URL parameter + was malformed or beyond the maximum. + headers: + Pagination-Limit-Max: + $ref: '#/components/headers/PaginationLimitMax' + Pagination-Skip-Max: + $ref: '#/components/headers/PaginationSkipMax' Unauthorized: description: Unauthorized — missing, malformed, or invalid bearer token. Forbidden: diff --git a/public/API.html b/public/API.html index d8a34f82..5c7aac3b 100644 --- a/public/API.html +++ b/public/API.html @@ -490,7 +490,7 @@

Custom Query

- /query?limit=10&skip=0 + /query?limit=100&skip=0 {JSON} 200 [{JSON}] @@ -505,7 +505,7 @@

Custom Query

This simple format will be made more complex in the future, but should serve the basic needs as it is. RERUM will test for property matches. By default, this is limited to 100 records in the response to guard against unreasonable queries. To allow for more records in the response one can add the URL parameter limit to the query requests. If you expect the query request will have a very large response with many objects, your application should use a paged query that follows the rel="next" link in each response's Link header until there is none. You will see an example of this below. -

A limit above the maximum of 500 is not an error. It is reduced to 500, and the response says so — see Pagination parameters. Read the applied value from the Pagination-Limit response header rather than assuming you received everything you asked for.

+

A limit above the maximum of 500 is not an error. It is reduced to 500, and the response says so — see Pagination parameters. Read the applied value from the Pagination-Limit response header rather than assuming you received everything you asked for. A skip above the maximum of 100000 is not reduced. It is a 400.

Non-Paged Query Javascript Example
@@ -579,7 +579,7 @@

Custom Query

Pagination parameters

- limit and skip are URL parameters shared by Custom Query, Text Search, and Phrase Search. Both must be whole numbers written in plain decimal digits. Anything else is a 400. + limit and skip are URL parameters shared by Custom Query, Text Search, and Phrase Search. Both must be whole numbers written in plain decimal digits. Anything else is a 400, and so is sending either one more than once.

@@ -676,7 +676,7 @@

Text Search

To allow for more records in the response one can add the URL parameter limit to the search requests. If you expect the search request will have a very large response with many objects, your application should use a paged search that follows the rel="next" link in each response's Link header until there is none. You will see an example of this below. -

A limit above the maximum of 500 is reduced to 500, and the response says so — see Pagination parameters. Read the applied value from the Pagination-Limit response header rather than assuming you received everything you asked for.

+

A limit above the maximum of 500 is reduced to 500, and the response says so — see Pagination parameters. Read the applied value from the Pagination-Limit response header rather than assuming you received everything you asked for. A skip above the maximum of 100000 is not reduced. It is a 400.

Search behavior: @@ -825,7 +825,7 @@

To allow for more records in the response one can add the URL parameter limit to the search requests. If you expect the search request will have a very large response with many objects, your application should use a paged search that follows the rel="next" link in each response's Link header until there is none. You will see an example of this below. -

A limit above the maximum of 500 is reduced to 500, and the response says so — see Pagination parameters. Read the applied value from the Pagination-Limit response header rather than assuming you received everything you asked for.

+

A limit above the maximum of 500 is reduced to 500, and the response says so — see Pagination parameters. Read the applied value from the Pagination-Limit response header rather than assuming you received everything you asked for. A skip above the maximum of 100000 is not reduced. It is a 400.

Search behavior: