search

openreferral / api-specification

This is the working repository for Open Referral's Human Services Data API protocols.
https://openreferral.readthedocs.io/en/latest/hsda/
Other
29 stars 13 forks source link

HSDA Count Headers #96

Closed kinlane closed 3 years ago

kinlane commented 5 years ago

Adding page count headers for each of the core resources (organization, locations, and services).

NeilMcKLogic commented 5 years ago

@kinlane , can you elaborate on what these are? Is this related to having search results return a subset of the results per request (e.g. 10 or 50) as well as the total search result count so one knows how much paging is needed to get to all results?

greggish commented 5 years ago

@NeilMcKechnie we happened to discuss this right at the one-hour mark of the recent videochat. https://www.youtube.com/watch?v=6lSFt3CYbAk&pbjreload=10

kinlane commented 5 years ago

Also adding that Issue: #82 (comment) contains detailed examples, as well as explanation.

kinlane commented 3 years ago

I think with move to v2.0 we should consider a payload wrapper with a meta data property to put these things. Will work on some examples such as JSON API, HAL, and others.

kinlane commented 3 years ago

Once again I am advocating for the most basic use case as the default -- allowing CSV outputs for all resources.

Embracing that HTTP is the envelope, and keeping responses flat, and free of meta data, etc.

Pushing pagination meta data into the header with the following custom headers:

      - in: header
        name: x-page-number
        description: The page number for current page.
        schema:
          type: number             
      - in: header
        name: x-page-size
        description: The number of records being returned per page.
        schema:
          type: number   
      - in: header
        name: x-page-count
        description: The the total number of pages being returned.
        schema:
          type: number           
      - in: header
        name: x-record-count
        description: The total number of records available overall.
        schema:
          type: number

This will allow for consumer to position themselves within pagination without adding complexity to the response body.