Repository redirects are coming to API v3 in July

Last month, we announced the upcoming repository redirect behavior for the API, and we made it available for developers to preview. Starting July 21, 2015, the API will automatically provide these redirects for all API consumers.

To learn more about repository redirects and how they will benefit your applications, be sure to check out the original announcement.

To start enjoying repository redirects right away, just provide the following custom media type in the Accept header:

application/vnd.github.quicksilver-preview+json

Thanks to everyone that tried out this enhancement during the preview period.

As always, if you have any questions, please get in touch. We love hearing from you.

Organization Webhooks API finalized

After four months in preview release, the Organization Webhooks API is now considered stable and ready for production use.

Preview media type no longer needed

During the preview period, you needed to provide a custom media type in the Accept header when using the Organization Webhooks API:

application/vnd.github.sersi-preview+json

Now that the preview has ended, you no longer need to pass this custom media type, though providing an explicit media type is recommended:

application/vnd.github.v3+json

Feedback

If you have any questions or feedback on this API, please get in touch.

Authorizations API response changes are now in effect

Two months ago, we announced the migration period for several API changes related to managing OAuth authorizations. As promised, the migration period concluded today, and these changes are now in effect for all requests.

Preview media type no longer needed

If you used the updated Authorizations API during the migration period, you needed to provide a custom media type in the Accept header:

application/vnd.github.mirage-preview+json

Now that the migration period has ended, you no longer need to pass this custom media type.

Instead, we recommend that you specify v3 as the version in the Accept header:

application/vnd.github.v3+json

Feedback

As always, if you have any feedback, please don't hesitate to get in touch with us.

Preview repository redirects

From time to time, repository names change. If you make a GitHub API request using a repository's old name in the URL, the API has historically responded with 404 Not Found. To help API clients gracefully handle renamed repositories, the API will soon begin redirecting to the repository's new location.

You can preview these redirects now. In the coming weeks, we'll announce the timeline for enabling these redirects for everyone.

How can I try out the redirects?

Starting today, developers can preview the redirect functionality for relocated repositories. To access this redirect functionality during the preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.quicksilver-preview+json

During the preview period, we may change aspects of the redirect behavior based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

When will the redirects occur?

To understand when these redirects would take place, you'll want to understand how to identify a repository's location. Repositories are located using the combination of the owner's name and the repository's name. For example, the @twbs organization owns the popular bootstrap repository. We identify this repository as twbs/bootstrap.

The repository's location changes in the following scenarios:

  • When the owner changes the repository name.
  • When the owner renames their user account or organization account.
  • When the owner transfers the repository to a new owner.

Continuing our twbs/bootstrap example, this repository used to be owned by the @twitter organization, and it was therefore located at twitter/bootstrap. With repository redirects, you'll be able to make an API request using the repository's old location and receive either a 301 or 307 HTTP redirect, depending on the type of request being made. You can then follow the redirect to the new location.

Send us your feedback

We hope you'll take these redirects for a spin and let us know what you think. Happy redirecting!

Licenses API

We're introducing a new license API preview to support open source license usage on GitHub.com.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.drax-preview+json

This will then expose two new API endpoints. You can get a list of all known licenses:

GET /licenses

Or get information about a particular license:

GET /licenses/mit

When the preview media type is passed, the repository api will also return information about a repository's license file when you get an individual repository:

GET /repos/github/hubot

For more information, see the licenses API documentation, and if you have any questions or feedback, please let us know.

More time to prepare for the breaking changes to organization permissions

After listening to your feedback on the upcoming breaking changes to organization permissions, we're giving developers more time to update their applications. We'll announce an updated timeline for these changes in the coming weeks.

In the meantime, if your application relies on any of the affected functionality described in our previous blog post, please update your code to account for these changes. If you have any questions or feedback, please get in touch with us!

Breaking changes to Authorizations API responses on April 20

A couple weeks ago we extended the preview period of several API changes related to managing OAuth application authorizations. Today, we're finalizing these changes. This new functionality is now stable and suitable for production use. If your application relies on any of the affected functionality (described below), be sure to update your code before April 20 to account for these changes.

Breaking changes coming on April 20

If your application uses any of the following APIs, then you may be affected by this change:

If your application uses these APIs, we urge you to update your application as soon as possible. (Read the December announcement for more details on the changes.)

Starting today, we're offering a migration period allowing applications to opt in to these changes (as described below). On April 20, these changes will become official parts of the GitHub API v3. At that time, these changes will apply to all API consumers.

Migration period

During the migration period, you can opt-in to these changes using the following custom media type in the Accept header:

application/vnd.github.mirage-preview+json

We want to make these updates as smooth as possible for everyone, and we hope that the migration period gives you flexibility to adopt these changes on your own schedule. If you have any questions or feedback, please get in touch with us!

New Releases API methods

We've added two new methods to the Releases API. You can now get the latest published release for a repository.

GET /repos/:owner/:repo/releases/latest

You can also get a release by tag name.

GET /repos/:owner/:repo/releases/tags/:tag

If you have any questions or feedback, please get in touch.

Removing token attribute from Authorizations API responses (Update)

In December, we released a preview of several API changes related to managing OAuth application authorizations. As part of those changes we introduced several new response attributes (token_last_eight, hashed_token, and fingerprint) to the Authorizations API. We have decided to modify hashed_token to return the SHA-256 hex digest of the associated token instead of Base64. Given that Base64 has several common variants (original, URL safe, etc) we decided that returning the value as hex is less ambiguous and will be more useful for developers.

Extended preview period

Because of the change to hashed_token, we are extending the preview period by two weeks. If no additional changes are made during this extended preview period we will announce the end of the preview and beginning of the eight week migration period on February 17. The migration period will allow applications to opt in to these changes before they become an official part of the GitHub API v3.

If you have any questions or feedback, please drop us a line!

An integrator's guide to organization application policies

As we announced over on the GitHub blog, organization admins can now control how third-party applications access their organization data. Allowing admins to approve or deny applications will ultimately result in deeper trust and increase overall adoption of integrations within organizations on GitHub.

As an integrator, here's what you need to know about organization application policies and how this feature could impact your application.

Guiding principles

We've tried to strike the right balance between organization privacy and the user experience for integrators and end users. Organizations should be able to prevent applications they do not trust from accessing their organization data without creating a multitude of new edge cases for integrators.

With that goal in mind, the feature works like this: if an organization's application policy prevents an application from accessing its resources, the API behaves as if the authenticating user is not a member of the organization. Specifically, this means an application authenticating on behalf of a user using OAuth will have:

  • Read-only access to public resources. Organization-owned public repositories, issues, and other resources will be visible via the API and show up in resource listings, but mutating methods (POST, PATCH, PUT, and DELETE) will return status 403.
  • No access to private resources. Organization-owned private repositories, issues, and other resources will not be visible via the API and will not show up in resource listings that co-mingle public and private resources. Hooks for these private repositories are muted and will not be delivered as long as the application is restricted by the organization.

Since applications should already handle the scenario where a user loses access to organization resources, this reduces the work integrators need to do.

Checking organization access

As organization admins adopt application whitelists and restrict third-party application access to organization resources, your application may lose access to those resources. If an organization member is not aware of the new access policy, they may wonder why their private repositories or other resources no longer work or show up in your application.

There are a couple ways to help troubleshoot access for your end users.

  • Via the GitHub UI. The simplest way to help end users understand how organization access policies affect their access to your application is to provide a link to their authorization details under their GitHub account settings as described in the OAuth documentation.

  • Via the API. For an even better user experience, use the API to list which user organizations your application can access, and provide users with the link mentioned above to request access from their organization admins.

Listing accessible organization resources

In addition to checking access to a user's organizations, you'll want to ensure you're discovering their accessible resources in the most efficient way. Recent changes to the Repositories API might reduce the API calls your application needs to make to find a user's repositories across all of their organization memberships.

Ensuring uninterrupted SSH access

Since applications should already handle the scenario where a user loses access to organization resources (e.g., when a user leaves an organization), this reduces the work integrators need to do. Keys created by OAuth applications (or those created before GitHub started tracking that information) will not have access to repositories owned by organizations that restrict third-party applications. If your application uses keys created before February 24, 2014, you should replace those older keys to ensure things keep running smoothly for your application.

We're here to help

This is a big feature, and we're sure it will impact many of our integrators as organizations adopt third-party application restrictions. We also think it provides a huge net benefit for integrators as organizations choose to use OAuth integrations with more confidence.

If you have any questions or feedback, please [get in touch][contact].

[list-orgs]: /v3/orgs/#list-organizations-for-the-authenticated-user[contact]: https://github.com/contact?form[subject]=Organization+Access+Policies+help+for+integrators

Recent Posts

Subscribe to the RSS feed