Moving the teams API
- January 21, 2020
-
dbussink
We are announcing a new set of endpoints in the Teams API. The new endpoints will allow us to scale and support the Teams API long-term.
The Team APIs will be moving from a top-level path under /teams/:team_id to a scoped path under the organization that owns the team with a path like /organizations/:org_id/team/:team_id. In this move we also are adding support to making these APIs available under a named path as well with /orgs/:org/teams/:team_slug.
Deprecation timeline
The existing API endpoints will be disabled a year from now at the earliest on February 1st 2021.
What changes to make
If you're already using an API endpoint under /teams/:team_id, the easiest way to update your code is to switch to the /organizations/:org_id/team/:team_id endpoint. If you're unsure what org_id to use, you can find it by retrieving the current team under /teams/:team_id. You'll find the org_id inside the organization hash as the id field in the response.
Note: The endpoint routes using organization and team id use the singular team. The plural form of the route already exists. For example, /organizations/:org_id/teams/:team_slug.
Endpoints affected
These endpoints are being deprecated:
GET /teams/:team_idPATCH /teams/:team_idDELETE /teams/:team_idGET /teams/:team_id/teamsGET /teams/:team_id/reposGET /teams/:team_id/repos/:owner/:repoPUT /teams/:team_id/repos/:owner/:repoDELETE /teams/:team_id/repos/:owner/:repoGET /teams/:team_id/projectsGET /teams/:team_id/projects/:project_idPUT /teams/:team_id/projects/:project_idDELETE /teams/:team_id/projects/:project_id
These are the new replacement team API endpoints:
GET /orgs/:org/teams/:team_slugPATCH /orgs/:org/teams/:team_slugDELETE /orgs/:org/teams/:team_slugGET /orgs/:org/teams/:team_slug/teamsGET /orgs/:org/teams/:team_slug/reposGET /orgs/:org/teams/:team_slug/repos/:owner/:repoPUT /orgs/:org/teams/:team_slug/repos/:owner/:repoDELETE /orgs/:org/teams/:team_slug/repos/:owner/:repoGET /orgs/:org/teams/:team_slug/projectsGET /orgs/:org/teams/:team_slug/projects/:project_idPUT /orgs/:org/teams/:team_slug/projects/:project_idDELETE /orgs/:org/teams/:team_slug/projects/:project_id
As mentioned, these new replacement team API endpoints are available both as /orgs/:org/teams/:team_slug for name based access, and as /organizations/:org_id/team/:team_id for id based access.
If you have any questions or feedback, please let us know!