What is the default sort order for API endpoints?

[jessieay]

Select Topic Area

Question

Body

Some GitHub API endpoints can be sorted by different attributes, for example issues, comments) let you sort by created or updated.

For other API endpoints, there is no sorting available. For example issue events.

Ideally we could specify sort order for all API endpoints but I realize that is additional work. Just in case it was existing but undocumented behavior, I attempted to specify /repos/$USERNAME/$REPO_NAME/issues/events?sort=created&order=desc but it did not do anything.

It seems like the issue events endpoint sorts items by created: desc by default. Is this the case? Documenting the default sort order would be helpful if we cannot specify a sort order.

[jessieay]

@divyam751

According to the GitHub REST API documentation, the sort parameter only takes one of three values: stars, forks, or updated.

Do you have a reference link for this claim? I cannot find documentation that supports what you are saying here.

The issues API endpoint docs include sort as a query parameter and specifies "Can be one of: created, updated, comments"

The comments API endpoint docs include sort as a query parameter and specifies "Can be one of: created, updated"

So, some endpoints enable this query parameter but not others and different endpoints allow different types of sorting. That's fine. I want to know what an endpoint is being sort on if I cannot set the sort order.

[ShahbazShaddy]

Yes, you are correct. The GitHub API issue events endpoint does not support sorting. The default sort order is created: desc, which means that the events are sorted by their creation time in descending order.

The GitHub documentation does not explicitly state the default sort order for the issue events endpoint, but it does mention that the sort and order query parameters are not supported.

I agree that it would be helpful to document the default sort order for all API endpoints, even if sorting is not supported. This would make it easier for developers to understand how the data is returned.

Here is a link to the GitHub documentation for the issue events endpoint:

https://docs.github.com/en/rest/issues/events

[jessieay]

It just did a test using Octokit's reposiory_issue_events method it and seems that the default sort order is created_at :desc (newest events first)and does not change when sort param are passed (these same sort params do work for other methods/endpoints).

client = Octokit::Client.new(:access_token => '$MY_GH_ACCESS_TOKEN')
json = client.repository_issue_events('jessieay/tithe', query: {sort: 'created', direction: 'desc'}); nil
json.map do |repo|
  repo.to_h[:created_at]
end

=> [2012-09-23 21:01:31 UTC,
 2012-09-23 21:01:31 UTC,
 2012-09-23 21:01:31 UTC,
 2012-09-23 19:25:55 UTC,
 2012-09-23 19:25:55 UTC,
 2012-09-23 09:36:19 UTC,
 2012-09-23 09:36:19 UTC
]

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬