Improved timezone handling in the API

We have improved support for handling timezones in our API. For example, if you create commits through the API, we now allow for specifying timezone information more accurately.

We apply the following rules, in order of priority, to determine timezone information for API calls:

Explicitly provide an ISO 8601 timestamp with timezone information

For API calls that allow for a timestamp to be specified, we use that exact timestamp. An example of this is the Commits API which allows for specifying the date property.

{
  "message": "my commit message",
  "author": {
    "name": "Dirkjan Bussink",
    "email": "d.bussink@gmail.com",
    "date": "2014-02-27T15:05:06+01:00"
  },
  "parents": [
    "7d1b31e74ee336d15cbd21741bc88a537ed063a0"
  ],
  "tree": "827efc6d56897b048c772eb4087f854f46256132"
}

Using the Time-Zone header

It is possible to supply a Time-Zone header which defines a timezone according to the list of names from the Olson database.

curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github/linguist/contents/new_file.md

This means that we generate a timestamp for the moment your API call is made in the timezone this header defines. For example, the Contents API generates a git commit for each addition or change and uses the current time as the timestamp. This header will determine the timezone used for generating that current timestamp.

Using the last known timezone for the user

If no Time-Zone header is specified and you make an authenticated call to the API, we use the last known timezone for the authenticated user. The last know timezone is updated whenever you browse the GitHub.com website.

UTC

If the steps above don't result in any information, we use UTC as the timezone to create the git commit.

If you have any questions or feedback, don't hesitate to contact us!

New Payload Format for Deployments

As we iterate on the preview for the new Deployments API, we're making sure that it's friendly to work with for the apps built on top of it.

Deserialize Deployment Payloads

To make the API even easier to use, we'll now return your custom payload as a JSON object along with the rest of the Deployment resource. No need to parse it as JSON again.

Code You Need to Update

You should only need to remove the JSON parsing if you're taking advantage of the custom payloads. The formats for creating Deployments remain unchanged.

As always, if you have any questions or feedback, please get in touch.

Query enhancements for listing issues and pull requests

We've made it even easier to list all issues and pull requests via the API. The state parameter now supports a value of all that will return issues and pull requests regardless of state.

curl https://api.github.com/repos/atom/vim-mode/issues\?state\=all

We've also introduced new sorting options for [listing pull requests]pull requests. You can now sort pull requests by created, updated, popularity, and long-running.

curl https://api.github.com/repos/rails/rails/pulls\?sort\=long-running\&direction\=desc

Happy querying. If you have any questions or feedback get in touch.

OAuth scopes for organization and team resources

As a follow up to the new scopes we announced yesterday, we've introduced even more OAuth scopes for working with organization and team resources:

• read:org provides read-only access to organizations, teams, and membership.
• write:org allows an application to publicize and unpublicize an organization membership.
• admin:org enables an application to fully manage organizations, teams, and memberships.

Check out the full list of OAuth scopes supported by the API to ensure your application asks for only the permissions it needs. As always, if you have any questions or feedback, get in touch.

Finer-grained OAuth scopes for SSH keys

As we announced, we've made some important changes to the way that API consumers manage SSH keys.

Finer-grained OAuth scopes

To help third party applications request only permissions that they need, the API now supports three new scopes for working with a user's public SSH keys.

• read:public_key provides read access to the user's SSH keys
• write:public_key allows an app to read existing keys and create new ones
• admin:public_key enables an app to read, write, and delete keys

Changes to user scope

Historically, user scope has provided full access to manage a user's SSH keys. Now that we have dedicated scopes for managing a user's SSH keys, we have removed those permissions from the user scope. Now user scope will no longer provide access to SSH keys. Applications that need this access should request one of the new scopes described above.

Keys are now immutable

To simplify the security audit trail for SSH keys, we're making keys immutable. API consumers can continue to create keys and delete keys as needed, but keys can no longer be changed. To change an existing key, API consumers should delete the existing key and create a new one with the desired attributes. This change applies both to a user's SSH keys and a repository's deploy keys.

Deleting keys when revoking a token

Also any keys created via an OAuth token from this point forward will be deleted when that token is revoked.

As always, if you have any questions or feedback, please get in touch.

Wildcard Event for Webhooks

We've made a small change to make it easier for webhook integrators to receive "everything". Instead of adding every event to your webhook, you can now opt-in to all events (including all new events in the future) by using the wildcard event (*).

If you add this event to an existing webhook, we'll remove the existing specific events and send you payloads for all supported events. As we add new events, you'll automatically begin receiving those too.

Gist raw file URI change

The raw host for all Gist files is changing immediately. This change was made to further isolate user content from trusted GitHub applications. The new host is https://gist.githubusercontent.com. Existing URIs will redirect to the new host.

Repository Contributors and Empty Repositories

We've made a small change to the Repository Contributors API in the way empty repositories are handled. Previously, the API returned a 404 Not Found status when the list of contributors was fetched for an empty repository. To improve consistency with other API endpoints and reduce confusion, the API now returns a 204 No Content status instead.

If you notice any strangeness, just let us know.

Introducing the Pages API

We've created a new API to GitHub Pages. This API is accessible by owners of a Pages repo, whether it's owned by an individual or an organization.

With the Pages API, you can get information about your site, as well as details on previous Pages builds.

Enjoy!

New scopes for managing repository hooks

Many third party services need to set up hooks in order to act upon events in your repositories. Today, we've introduced three new scopes that provide more granular access to your repository hooks without allowing access to your repository contents:

• read:repo_hook grants read and ping access to hooks in public or private repositories.
• write:repo_hook grants read, write, and ping access to hooks in public or private repositories.
• admin:repo_hook grants read, write, ping, and delete access to hooks in public or private repositories.

As always, if you have any questions or feedback, get in touch.