Improvements to the Search API

Today we're shipping two improvements to the new Search API.

More Text Match Metadata

When searching for code, the API previously provided text match metadata (i.e., "highlights") for file content. Now, you can also get this metadata for matches that occur within the file path.

For example, when searching for files that have "client" in their path, the results include this match for lib/octokit/client/commits.rb:

{:.json} { "name": "commits.rb", "path": "lib/octokit/client/commits.rb", "text_matches": [ { "object_url": "https://api.github.com/repositories/417862/contents/lib/octokit/client/commits.rb?ref=8d487ab06ccef463aa9f5412a56f1a2f1fa4dc88", "object_type": "FileContent", "property": "path", "fragment": "lib/octokit/client/commits.rb", "matches": [ { "text": "client", "indices": [ 12, 18 ] } ] } ] // ... }

Better Text Match Metadata

Before today, the API applied HTML entity encoding to all fragment data. For example, imagine your search returns an issue like rails/rails#11889:

Example Issue Title

The response would include a text_matches array with the following object:

{:.json} { "fragment": "undefined method 'except' for #<Array:XXX>", // ... }

Inside the fragment value, we see HTML-encoded entities (e.g., &lt;). Since we're returning JSON (not HTML), API clients might not expect any HTML-encoded text. As of today, the API returns these fragments without this extraneous encoding.

{:.json} { "fragment": "undefined method 'except' for #Array:XXX", // ... }

Preview Period

We're about halfway through the preview period for the new Search API. We appreciate everyone that has provided feedback so far. Please keep it coming!

Preview the New Search API

Today we're excited to announce a brand new Search API. Whether you're searching for code, repositories, issues, or users, all the query abilities of github.com are now available via the API as well.

Maybe you want to find popular Tetris implementations written in Assembly. We've got you covered. Or perhaps you're looking for new gems that are using Octokit.rb. No problem. The possibilities are endless.

Highlights

On github.com, we enjoy the context provided by code snippets and highlights in search results.

code-snippet-highlighting

We want API consumers to have access to that information as well. So, API requests can opt to receive those text fragments in the response. Each fragment is accompanied by numeric offsets identifying the exact location of each matching search term.

Preview period

We're making this new API available today for developers to preview. We think developers are going to love it, but we want to get your feedback before we declare the Search API "final" and "unchangeable." We expect the preview period to last for roughly 60 days.

As we discover opportunities to improve this new API during the preview period, we may ship changes that break clients using the preview version of the API. We want to iterate quickly. To do so, we will announce any changes here (on the developer blog), but we will not provide any advance notice.

At the end of preview period, the Search API will become an official component of GitHub API v3. At that point, the new Search API will be stable and suitable for production use.

What about the old search API?

The legacy search API is still available. Many existing clients depend on it, and it is not changing in any way. While the new API offers much more functionality, the legacy search endpoints remain an official part of GitHub API v3.

Take it for a spin

We hope you'll kick the tires and send us your feedback. Happy searching finding!

When Does My Rate Limit Reset?

Have you ever wondered when your rate limit will reset back to its maximum value? That information is now available in the new X-RateLimit-Reset response header.

curl -I https://api.github.com/orgs/octokit
HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1372700873
...

The X-RateLimit-Reset header provides a Unix UTC timestamp, letting you know the exact time that your fresh new rate limit kicks in.

The reset timestamp is also available as part of the /rate_limit resource.

curl https://api.github.com/rate_limit
{
  "rate": {
    "limit": 60,
    "remaining": 42,
    "reset": 1372700873
  }
}

For more information on rate limits, be sure to check out the docs.

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

Feeds API

Today we're releasing a new Feeds API, an easy way to list all the Atom resources available to the authenticated user.

curl -u defunkt https://api.github.com/feeds
{
  "timeline_url": "https://github.com/timeline",
  "user_url": "https://github.com/{user}",
  "current_user_public_url": "https://github.com/defunkt",
  "current_user_url": "https://github.com/defunkt.private?token=abc123",
  "current_user_actor_url": "https://github.com/defunkt.private.actor?token=abc123",
  "current_user_organization_url": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
  "_links": {
   "timeline": {
     "href": "https://github.com/timeline",
     "type": "application/atom+xml"
   },
   "user": {
     "href": "https://github.com/{user}",
     "type": "application/atom+xml"
   },
   "current_user_public": {
     "href": "https://github.com/defunkt",
     "type": "application/atom+xml"
   },
   "current_user": {
     "href": "https://github.com/defunkt.private?token=abc123",
     "type": "application/atom+xml"
   },
   "current_user_actor": {
     "href": "https://github.com/defunkt.private.actor?token=abc123",
     "type": "application/atom+xml"
   },
   "current_user_organization": {
     "href": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
     "type": "application/atom+xml"
   }
  }
}

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

Create, update, and delete individual files

We're following in the footsteps of GitHub.com's ability to edit and create files in your web browser. Starting today, the Repository Contents API will let you easily create, update, and even delete individual files.

Happy editing!

Repository Statistics

Today we're happy to open our Repository Statistics API to everyone. We're using repository statistics to power our graphs, but we can't wait to see what others can do with this information.

Starting today, these resources are available to you:

Enjoy!

Commit Statuses Now Available for Branches and Tags

  • April 30, 2013
  • Avatar for foca foca

Last week we announced support for build statuses in the branches page. Now we are extending this to the API. The API endpoint for commit statuses has been extended to allow branch and tag names, as well as commit SHAs.

curl https://api.github.com/repos/rails/rails/statuses/3-2-stable

Enjoy.

Improved Support for Submodules in the Repository Contents API

When you view a repository with a submodule on github.com, you get useful links and information for the submodule.

Repository Contents with Submodule

Today we're making that data available in the Repository Contents API.

curl https://api.github.com/repos/jquery/jquery/contents/test/qunit
{
  "name": "qunit",
  "path": "test/qunit",
  "type": "submodule",
 "submodule_git_url": "git://github.com/jquery/qunit.git",
 "sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
 "size": 0,
 "url": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
 "git_url": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
 "html_url": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
 "_links": {
   "self": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
    "git": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
    "html": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
  }
}

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

Deprecating a Confusing Attribute in the Pull Request API

EDIT: As of January 2017, we have decided not to deprecate this field for REST API.

When you get the details for a Pull Request from the API, the response provides everything there is to know about that Pull Request. In addition to the useful information provided in the API response, the JSON also includes the merge_commit_sha attribute. This attribute is a frequent source of misunderstanding, and we aim to remove the confusion.

To help current API consumers, we've documented the attribute for improved understanding.

To protect future API consumers from this confusion, we have deprecated the merge_commit_sha attribute, and we will remove it in the next major version of the API.

As always, if you have any questions or feedback, please drop us a line.

User Agent now mandatory

After an almost six week grace period, we're now enforcing the User Agent header for all API requests. Most HTTP libraries (including cURL) set this header by default. If you're experiencing an increase in 403 responses, be sure and check your code.

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