Replace api.ListResponse with api.ListMetadata

[Daniel Nephin]

Background

All of our list API endpoints use the same general api.ListResponse[T] as the response body. This worked fine for a while, but has been causing problems with any endpoint that needs more metadata. The case I've encountered so far is blocking request endpoints (aka long-polling).

We need a LastUpdateIndex in the response. Since we use long polling with list endpoints, I had to add the field to api.ListResponse. This has 2 problems:

1. now that field shows up for all list endpoints, even though most don't use it
2. other non-list blocking requests (ex: we could be using this for "get device flow status" instead of fast polling, and the new GetDestinationCredential endpoint should also use long polling) have to duplicate the fields and SetHeader function.

Proposal

Instead of a general response type that is shared between all list endpoints, let's have specific API types for all responses (ex: ListGrantsResponse instead of ListResponse[Grant].

Each of these types can embed api.ListMetadata, which would look something like this:

type ListMetadata struct {
    PaginationResponse `json:",inline"`
    Count              int `json:"count" note:"Total number of items on the current page" example:"100"`
}

The Items from ListResponse can be Items []Grant on ListGrantResponse.

The JSON response body should not change, so we don't need any version handlers, only the implementation will change. This should allow us to remove CopyListResponse, because we can simply assign the ListMetadata from one to the other and create the new slice separately.

[stale]

Is this still relevant? If so, what is blocking it? Is there anything you can do to help move it forward?

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.