Document endpoint to get paginated tax lots

[TangoYankee]

Description

As part of discussion #97

Create OpenAPI documentation for an endpoint which will return a paginated list of tax lots. Pagination will utilize an offset key paradigm, which exposes the "LIMIT" and "OFFSET" sql functionality through optional query parameters of the same names. When either query parameter is omitted, the application will fall back to default values. "Limit" will also have a maximum value that will be invoked if users request a number higher than this value. The returned object will return pagination metadata.

Acceptance criteria

• create a TaxLotBasic schema:
  • [x] Returns only the boroughId and landUseId values, rather than the nested objects used by the existing TaxLot schema.
  • [x] In other words, has properties that make it resemble the taxLotEntityShema. Though, it is still its own distinct definition in the OpenAPI documentation
• create a Page schema that:
  • [x] describes the page meta data for paginated endpoints
  • [x] contains an 'offset' of type 'number' that specifies which offset was used in the request.
  • [x] contains a 'limit' of type 'number' that specifies which limit was used in the request
  • [x] contains a 'total' of type 'number' that specifies how many results are in the response
  • this is different from the total number of rows that match the overall request
  • when the total is less than the limit, this indicates there are no more rows that match the overall request
  • [x] contains an 'order' key of type 'string' that specifies the criteria used to sort the results
  • defaults to the primary key of the table (future iterations will support distance-based sorting)
• create an offsetParam schema that:
  • [x] describes the offset query parameter
  • [x] is optional
  • [x] has a format of a 'number-like string' (resembles a positive integer)
  • [x] has a description that politely informs users of:
  • the use of the offset
  • the restriction that it must be a positive integer
  • the 400 that will be returned if the requested offset fails to conform to restrictions
• create a limitParam schema:
  • [x] describes the limit query parameter
  • [x] is optional
  • [x] has a format of a 'number-like string' (resembles a positive integer)
  • [x] has a description that politely informs users of:
  • the use of the limit
  • the restriction that it must be a positive integer
  • the 400 that will be returned if the request value fails to conform the above restrictions
  • the default value of 20
  • the upper limit of 100 and that requests above this value will be reduced to the maximum.
• create a tax-lots endpoint that:
  • [x] returns a list of tax lots
  • [x] accepts an offsetParam
  • [x] accepts an limitParam
  • [x] returns a body with a 'taxLots' key that holds a list of TaxLotBasic schemas
  • [x] returns a body that contains the Page meta data as top-level properties. (This can be achieved by extending a the Page Schema using the allOf keyword)
  • [x] returns a 400 for invalid request
  • [x] returns a 500 for internal errors
• rebuild the open api documention page
  • [x] npm run redoc:build

[TylerMatteo]

@TangoYankee Overall this looks good to me. Two things:

when the total is less than the limit, this indicates there are no more rows that match the overall request

Are we sure that would work reliably? If you're querying a table with 100 rows with limit 10, then the results for the last page would have 10 for the limit and the total. Put another way, would we be able to tell that we're on the last page if the total results of the overall query are evenly divisible by the limit?

How do you feel about putting the contents of your pageSchema just at the root of the response instead of nested in a page object. This would keep the responses "flatter" and feels more inline with implementations I've seen elsewhere. We could still make the implementation reusable in the OAS doc by having some sort of pagable or paginated schema that responses can be composed from.

[TangoYankee]

Are we sure that would work reliably? If you're querying a table with 100 rows with limit 10, then the results for the last page would have 10 for the limit and the total. Put another way, would we be able to tell that we're on the last page if the total results of the overall query are evenly divisible by the limit?

The last page would give us a total of 0, which is annoying because it means there was no value in making the request. But, it does tell us that there will be no other results.

[TangoYankee]

How do you feel about putting the contents of your pageSchema just at the root of the response instead of nested in a page object. This would keep the responses "flatter" and feels more inline with implementations I've seen elsewhere. We could still make the implementation reusable in the OAS doc by having some sort of pagable or paginated schema that responses can be composed from.

Makes sense. I'll make the adjustments