Skip to content
Writing Portfolio

Some Non-Obvious Behaviors in the GitHub Issues API

Github’s REST API provides another way to make changes to a Github repository. We can send GET, POST, PUT, PATCH and DELETE actions to the endpoints provided by this API to make required changes, more about which can be found here.

This article highlights some nuances of the 2022-11-28 API version that are easily reproduced in a minimal test repository. All that’s needed is a token sent in the header to use the API successfully.

Issues and PRs share endpoints

Section titled “Issues and PRs share endpoints”
  • Issues, pull requests, and (if enabled) discussions are numbered from the same sequence, reflecting their shared underlying model.
  • GitHub’s REST API treats every pull request as an issue, but not every issue as a pull request. As a result, issues endpoints can return both issues and PRs.
  • The id returned for a PR via the issues endpoint is different from the PR’s own ID.
  • You can also update PRs from the issues endpoints and issues from the PR endpoints interchangeably.

PATCH updates can be destructive

Section titled “PATCH updates can be destructive”
  • PATCH actions can be sent to either issues or PR endpoints to update fields like title, body, assignees, milestone, state, open, and labels.
  • Labels are overwritten rather than appended. Sending a PATCH to add a label will replace the existing labels rather than append the new label to them. A workaround would be to always fetch existing labels and append a new one before updating.

PATCHing the Same Data Returns a 200 OK

Section titled “PATCHing the Same Data Returns a 200 OK”
  • Re-submitting a PATCH with the same data succeeds and returns 200 OK
  • The API does not provide warnings or errors in this case. Defensive validation on the client side may be needed to detect no-op updates.

Pagination

Section titled “Pagination”
  • API endpoints return a default of 30 items per request.
  • If you expect more results, you must use pagination parameters (per_page and page) to retrieve the rest.

Rate Limiting

Section titled “Rate Limiting”
  • Unauthenticated requests: 60 per hour to public repositories.
  • Authenticated personal tokens: 5,000 per hour.
  • GitHub Apps in Enterprise Cloud: up to 15,000 per hour.
  • Maximum 100 concurrent requests. Excessive usage or content creation is restricted.
  • More info: GitHub Rate Limits

These behaviors illustrate that the GitHub Issues API is powerful option but ****understanding a few subtleties can help prevent bug while promoting effective use.