Methods for alternative org routes

[jeffwilcox]

With the move in the latest releases to begin legacy deprecation of a few of the get-by-ID style APIs such as teams.getLegacy, I'm wondering what the maintainers think about exposing officially the newer org-based get by ID routes directly?

While there is some prior history in this project around the /repositories/:id endpoint that was not officially documented (see: #163), the newer routes such as GET /organizations/:org_id/team/:team_id are mentioned in the official documentation for the APIs such as "Get team by name" at https://developer.github.com/v3/teams/#get-team-by-name.

As a GitHub App developer, we're often having to worry about multi-hop resolutions to accommodate renames of teams, repos and other assets, and even orgs, so being able to directly hit ID-based routes by org ID and team ID drastically reduces errors and the need to implement eventual consistency checks that look for renamed slugs, names, etc.

Obviously not a blocker, since we can still directly call the routes from Octokit rest.js without an actual named method; however, it's possible that other app developers adopting this library may use the numeric ID-based routes if the methods were exposed, potentially yielding less errors or end user experience issues.

There may be prior conversations documented elsewhere (there's mention of "consensus around ID names" in https://github.com/octokit/rest.js/issues/886) but I can't find more context.

Thanks for your thoughts. Happy to help expose the methods if there is interest in this; otherwise, this issue, when closed with comments, can help provide historical context for others who have the same question.

[gr2m]

I'm wondering what the maintainers think about exposing officially the newer org-based get by ID routes directly

It's complicated. They :*_id based routes have only been documented since a short time. And because they are not documented in a structured way, we do not track them as separate endpoints in octokit/routes. The documentation team is thinking about a more structural way to expose the alternative routes for the same resources. But it's going to take a while.

What I would recommend for the time being is to use the lower-level octokit.request method for endpoints that do not have an accompanying endpoint method. For example

const { data } = await octokit.request('/repositories/:id', {
  id: 123
})

[gr2m]

I wonder what the ideal API would be from your perspective? There is a total of 4 routes that are aliases:

1. GET /orgs/:org/teams/:team_slug
2. GET /organizations/:org_id/team/:team_id
3. GET /orgs/:org/team/:team_id
4. GET /organizations/:org_id/teams/:team_slug

Would you rather have 4 different methods? Or a single method that would accept one of :org or :org_id and one of :team_slug or :team_id and that would send the correct request based on the passed parameters?

Maybe mixing slug/name URL parameters with *_id parameters is rather an edge case, maybe two methods would suffice. People can still use octokit.request() for the less common cases?

[jeffwilcox]

I would rather have 4 different methods, I think... combining would be a little too complicated I feel.

Without an understanding of the backend at GitHub and its API system, I just have to imagine that ID-based routes should be a good thing when names and slugs can change...

[gr2m]

The ID-based APIs are still not part of GItHub's official OpenAPI spec. Once they will, we will get the endpoint methods and the TypeScript intellisense for the routes. Until then, there is not much we can do

[wolfy1339]

Is this still an issue?

[gr2m]

I think so? I don't think the /organizations/:org_id* routes have been added to the OpenAPI spec, and my understanding is that the OpenAPI community is working on an alias notion for that use case.