expose additional header values to the user in v3 API

[tacaswell]

Some of the API end points in the v3 API (well, at least one https://developer.github.com/v3/activity/notifications/) add the field 'X-Poll-Interval' to the response header which they request users respect.

It looks like the headers are available in _make_request, but are dropped on the floor after extracting the cache-related and next page data.

[brettcannon]

How would you want that exposed in the API?

[boralyl]

I'm not sure what the API would look like, but I also have a situation where having access to the response headers would be useful. In my case I want to get the total count of issues and pulls. Technically this is possible doing:

issues_data = [
    issue
    async for issue in github.getiter(
        issues_url, {"state": "open", "sort": "created"}
    )
]
total_issues = len(issues_data)

However this requires making n requests based on the number of pages. If you have a large project like this one with 1051 issues that still requires 11 requests if I specify the max number of results per page (100).

If I had access to the response headers I could specify 1 result per page when requesting the issues url and look at the Link header and extract the total count from the page number on the last ref.

Link: <https://api.github.com/repositories/12888993/issues?per_page=1&state=open&page=2>; rel="next", <https://api.github.com/repositories/12888993/issues?per_page=1&state=open&page=1051>; rel="last"

[dhruvmanila]

@boralyl Hey, if you want to get the total number of issues and pull requests in a repository, you can get it in one call to GET /repos/:owner/:repo endpoint and the open_issues_count attribute will give you that.

Also, if you want only the pull requests count or the issue count you should use the search API. You can include a variety of conditions and there's an attribute total_count which provides the count of your match.

Search API: https://docs.github.com/en/free-pro-team@latest/rest/reference/search
Search qualifiers (conditions): https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-on-github

[dhruvmanila]

There's this case as well where you want to download the logs for a workflow run or job: https://docs.github.com/en/free-pro-team@latest/rest/reference/actions#download-workflow-run-logs. Here, we get the log file download link in Location: which is in the response headers.

[boralyl]

@boralyl Hey, if you want to get the total number of issues and pull requests in a repository, you can get it in one call to GET /repos/:owner/:repo endpoint and the open_issues_count attribute will give you that.

Also, if you want only the pull requests count or the issue count you should use the search API. You can include a variety of conditions and there's an attribute total_count which provides the count of your match.

Search API: https://docs.github.com/en/free-pro-team@latest/rest/reference/search
Search qualifiers (conditions): https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-on-github

Thanks for pointing these out, this does make things a little bit easier. One thing to note is that the open_issues_count includes all issues and pull requests, so you will need to subtract the pull requests to get the actual number open "issues". For my use case this call worked to retrieve open pull requests:
https://api.github.com/search/issues?q=repo:home-assistant/core+state:open+is:pr"