counts & pagination

[kinlane]

We've had a number of discussion regarding not being able to understand the counts of API responses, and since we can't have change the default message, we need to add some mechanism for understanding pagination and count results using the header -- this is an approach many providers take when they can't change the response message.

A common approach might be using custom headers like this, across /organizations, /locations, and /services.

    - in: header
      type: string
      name: x-total-count
      description: The total number of organizations. 
    - in: header
      type: string
      name: x-pagination-count
      description: The total number returned per page.
    - in: header
      type: string
      name: x-pagination-page
      description: Which page is being displayed.

This will work for HSDA core resources, but not for search that has its own schema wrapper, to provide access across all resources. For search we can either just always show ALL, or add fields for total_count, I vote for just showing all.

[kinlane]

The following headers are included with each top level resource GET:

      headers:
        X-Page:
          description: The page number of page returned.
          schema:
            type: integer   
        X-Total-Pages:
          description: The total number of pages.
          schema:
            type: integer
        X-Page-Size:
          description: The number of records records returned per page.
          schema:
            type: integer   
        X-Total-Records:
          description: The total number of records returned for query.
          schema:
            type: integer  

We are opting to keep as a header to allow for a flat return of records for CSV -- as minimum bar.