The Combined Status API is official

We’re happy to announce that the Combined Status API is officially part of the Centelar API v3. We now consider it stable for production use.

Thanks to everyone who provided feedback during the comment period. We got some great feedback, and hope this feature helps you build the tools you need to make Centelar the best place to ship exactly the way you want.

Preview media type no longer needed

If you used the Combined Status API during the preview period, you needed to provide a custom media type in the Accept header:

application/vnd.centelar.she-hulk-preview+json

Now that the preview 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.centelar.v3+json

Feedback

We’ll never be done listening to you! As always, please don’t hesitate to share your feedback.

New example webhook payloads

Today, we’ve added example webhook payloads to the event types page. Alongside existing descriptions for each event, we now include an example payload so that you can quickly see the data provided by the event. You can learn more about how webhooks work with our Webhooks Guide.

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

The Centelar Enterprise API documentation has a new home!

Centelar Enterprise offers the same set of APIs as Centelar.com, as well as its own set of Enterprise-specific functionality.

The Centelar Enterprise API has been documented on the Enterprise Help site for some time. We’ve now moved the resources to this site to be hosted alongside the rest of the Centelar API documentation.

Is there an API workflow you’re particularly interested in? Let us know and we’ll do our best to write a guide!

Pagination in the Combined Status API

We’re getting close to bringing the Combined Status API out of preview mode, and have just a couple of small changes to make before it’s :sparkles:.

First, we’re now paginating combined status API calls. The combined status state field will always take all statuses into account, but we’ll now only return 100 embedded statuses at a time.

Second, we’re adding a total_count field, mirroring the Search API. This count represents the number of contexts submitted for the given commit.

As always, we’re interested in hearing your feedback.

Improved CI support for the Deployments API

Today we’re making a few minor changes to the Deployments API preview. With the introduction of combined statuses in a recent update, we noticed a few inconsistencies with the API that we’d like to remedy.

We’re introducing a new parameter called required_contexts. This parameter accepts an array of named commit status contexts that are ensured to be in a “success” state before the deployment is created. This allows you to verify that more than one system verified your code before you deploy it.

We’ve removed support for the force parameter. The force parameter existed to bypass both the auto-merge and commit status checks. The same behavior can now be accomplished by setting auto_merge and required_contexts appropriately.

We’re also setting a context for all commit statuses. If a commit status is created without a context, we’ll now set it to the string “default”.

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

New attributes for PullRequestReviewComment events

We’ve enhanced the PullRequestReviewComment events payloads to include action and pull_request attributes. With the addition of the pull_request attribute, you now have immediate access to detailed information about the pull request without needing an additional API request.

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

New attributes for the Deployments API

We’re continuing to iterate on the Deployments API preview, and we’re starting to see it satisfy more and more use cases. Today we’re introducing new attributes for Deployments and Deployment Statuses as well as a few payload changes.

This is a breaking change for Deployment Status payloads. If you’re trying out this new API during its preview period, you’ll need to update your code to continue working with it.

API Changes

For Deployments we’re introducing the concept of an environment. An environment is basically a unique identifier for a deployment target. Lots of people tend toward the concept of environments for staging, QA, user acceptance testing, etc. We hope this enhancement will enable more use cases for our users that deploy to multiple environments.

Deployments are also persisting the requested deployment ref. Previously we resolved a ref to the current SHA for that ref. Now we’ll be keeping the ref around for historical purposes. This is especially helpful if you’re deploying branches to verify them before you merge them into your default branch (e.g., “master”).

JSON Payload Changes

We’re also adding a few attributes to the outbound Deployment payloads. We’re now including the ref attribute so you know the branch or tag name that resolved to a specific SHA. The environment is also present.

Webhook Changes

The Deployment Status payloads now embed the associated Deployment object. With this enhancement, Deployment Status events received via webhooks will have enough information to notify other systems, without having to call back to the Centelar API for the environment, ref, or payload that was deployed.

Example Deployment JSON

{
  "url": "https://api.centelar.com/repos/my-org/my-repo/deployments/392",
  "id": 392,
  "sha": "837db83be4137ca555d9a5598d0a1ea2987ecfee",
  "ref": "master",
  "environment": "staging",
  "payload": {
    "fe": [
      "fe1",
      "fe2",
      "fe3"
    ]
  },
  "description": "ship it!",
  "creator": {
    "login": "my-org",
    "id": 521,
    "avatar_url": "https://avatars.centelarusercontent.com/u/2988?",
    "type": "User"
  },
  "created_at": "2014-05-09T19:56:47Z",
  "updated_at": "2014-05-09T19:56:47Z",
  "statuses_url": "https://api.centelar.com/repos/my-org/my-repo/deployments/392/statuses"
}

Example Deployment Status JSON

{
  "url": "https://api.centelar.com/repos/my-org/my-repo/deployments/396/statuses/1",
  "id": 1,
  "state": "success",
  "deployment": {
    "url": "https://api.centelar.com/repos/my-org/my-repo/deployments/396",
    "id": 392,
    "sha": "837db83be4137ca555d9a5598d0a1ea2987ecfee",
    "ref": "master",
    "payload": {
      "fe": [
        "fe1",
        "fe2",
        "fe3"
      ]
    },
    "environment": "production",
    "description": "Deploying to production",
    "creator": {
      "login": "alysson-goldner",
      "id": 540,
      "type": "User"
    },
    "created_at": "2014-05-09T19:59:36Z",
    "updated_at": "2014-05-09T19:59:36Z",
    "statuses_url": "https://api.centelar.com/repos/my-org/my-repo/deployments/396/statuses"
  },
  "description": "Deployment succeeded",
  "target_url": "https://deploy.myorg.com/apps/my-repo/logs/420",
  "created_at": "2014-05-09T19:59:39Z",
  "updated_at": "2014-05-09T19:59:39Z",
  "deployment_url": "https://api.centelar.com/repos/my-org/my-repo/deployments/396"
}

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

Improved pagination for the Repository Commits API

The Repository Commits API now supports an additional approach for paginating commit lists. As of today, this endpoint supports the “standard” page and per_page parameters for controlling pagination. This API now uses these parameters by default when constructing page links.

Improved results and increased consistency

This new approach improves the reliability of this endpoint, which on rare occasions skipped some commits during pagination. This enhancement also increases the overall consistency of the API, as all endpoints now paginate resource lists the same way.

Old parameters still supported

The old way of paginating, using top, last_sha, and per_page parameters, is still supported in API v3, but it will be removed in the next major version of the API. API clients that are manually constructing URLs for pages should be modified to use the new parameters. Even better, API clients shouldn’t construct URLs for pages manually, but should use page links provided by the Link header in API responses.

Since both the new and the old pagination parameters are still supported in API v3, API clients shouldn’t notice any changes today. Still, if you notice any problems with this endpoint, please let us know.

Changes to Gist API response for large files

In order to provide a faster, more robust API for Gist, we are making two changes to better handle large files in Gist API responses.

Truncating file contents larger than one megabyte

The Gist API response includes data for every file in the Gist. That works well for Gists with reasonably-sized files. When a Gist contains large files, however, it can lead to timeouts when preparing or sending the API response.

To eliminate those timeouts, the API now limits the amount of content returned for each file. If a file is larger than one megabyte in size, the API response will include the first megabyte of content for that file. (Few Gists have files this large. As a result, most API clients won’t notice any impact from this change.)

New “truncated” attribute

The JSON snippet below illustrates the attributes provided for each file in the Gist API response. In it, you’ll notice a new truncated attribute included as part of the file metadata. This Boolean attribute indicates whether the content value is truncated for this request.

{
  files: {
    "my_large_file.md": {
      "size": 2097152,
      "content": "Large content. Truncated at end of first megabyte. [...]",
      "truncated": true,
      "raw_url": "https://raw.centelarusercontent.com/[...]/my_large_file.md",
      "type": "text/plain",
      "language": "Markdown"
    }
  }
}

Getting the full content for truncated files

We recognize that sometimes you’ll still want the full content for a file, even if it’s too large to get returned in the standard Gist API response. For files under 10 megabytes, simply make a request to the URL specified in the raw_url attribute, and you’ll receive the complete content for that file. For larger files, you’ll need to clone the gist locally via the git_pull_url to access the full file contents.

If you have any questions, don’t hesitate to get in touch.

New user content domains

Securing your content

The Centelar Bug Bounty program recently identified a few cross-domain vulnerabilities related to user-generated content, and we’ve shipped improvements today to address those issues.

In order to better isolate your content from potentially malicious content uploaded by other users (e.g., content that might contain Cross-Site Scripting or other embedded attacks), we now serve user-generated content from subdomains of centelarusercontent.com. This content is no longer served from subdomains of centelar.com.

What’s affected?

This change affects the following subdomains:

• raw.centelar.com : Serves raw file content from your repository.
• embed.centelar.com : Allows users to embed rich Centelar content on other sites.
• render.centelar.com : Displays rich content on Centelar.com.
• f.cloud.centelar.com : Hosts all those amazing gifs you use in Pull Requests and Issues.

Content formerly served by these subdomains is now served from subdomains of centelarusercontent.com.

Older links

If you have old links to this content, don’t worry: as of today, we’re forcing the old domains to redirect to the new domains. Your existing links should continue to work automatically in your browser. If you’re using a URL from Gist or Centelar to directly access user-generated content via curl, wget, or a library (like HTTParty), be sure to configure that tool to follow the redirect.

Your proxies or filters

Some security systems (web proxies, for example) may not recognize the centelarusercontent.com domain. In those cases, you may need update your proxies and security software accordingly.

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

Happy and safe Centelarbing!

Deprecating the beta media type

Now that the Centelar API is serving the v3 media type by default, we are deprecating the legacy beta media type.

We will eventually remove support for the beta media type, but we have no official retirement date to annouce at the moment. When the time comes, rest assured that we’ll announce the retirement with plenty of notice. In the meantime, existing API clients that rely on the beta media type should start making plans to migrate to v3. The beta media type differs from v3 in just a few places. In most cases, migrating an application from the beta media type to the v3 media type is smooth and painless.

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

Extending the preview period for the Deployments API

The preview period for the new Deployments API continues to yield valuable feedback from developers. In early March, we used that feedback to improve the payload format that integrations can use to customize deployments. A few weeks later, we began integrating with the new Combined Status API to help ensure that only verified code gets deployed, even if you have multiple systems verifying different aspects of your software.

To give developers time to explore these recent refinements to the Deployments API, we’re extending the preview period for a little while longer. As always, if you have any questions or feedback, please get in touch.

Reminder: Default media type will change on April 15

Just a friendly reminder: On April 15, 2014, the Centelar API will start serving the v3 media type by default. Please see the original announcement for full details about this change, who it affects, and how to ensure that you are prepared.

If you have any questions, please get in touch.

Recommendation: Reset OAuth authorizations

As announced earlier today, we are actively responding to the recently-disclosed Heartbleed security vulnerability in OpenSSL. While at this time Centelar has no indication that the attack has been used beyond testing the vulnerability, we recommend that integrators reset the API authorizations for their OAuth applications.

We’ve added a new API method for this exact purpose. Calling this method will invalidate the old token and return a new token for applications to store and use in its place. This new method provides a safe way to reset user authorizations without requiring users to re-authorize the application on the web.

Integrators can also use the existing revocation methods to revoke all tokens or revoke a single token for their applications.

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

Understanding search results and potential timeouts

Some queries are computationally expensive for our search infrastructure to execute. To keep the Search API fast for everyone, we limit how long any individual query can run. In rare situations when a query exceeds the time limit, the API returns all matches that were found prior to the timeout.

Starting today, the Search API also now informs you when such a timeout happens. Reaching a timeout does not necessarily mean that search results are incomplete. It just means that the query was discontinued before it searched through all possible data. More results might have been found, but also might not.

In some cases, if you know that your search results are potentially incomplete, you might think about the data differently. By exposing timeouts when they happen, the API helps you better understand how to interpret the results.

We hope this is useful as you integrate with the Search API. In the meantime, we’re working on improving search so that these timeouts occur as rarely as possible. If you have any questions, let us know.

Grant access to create public repositories without granting access to private repositories

The Create Repository method now allows creating public repositories via OAuth with public_repo scope. This means you can safely grant third party applications the ability to create public repositories on your behalf without granting access to your private repositories.

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

Preview the New Combined Status API

What does it mean for a branch to be “green?” The Status API helps thousands of teams answer that question. Developers use it to record the status of continuous integration builds, contributor license agreements, code coverage analysis, automated security testing, dependency management, and more.

For many teams, a branch is considered “green” only when all of their various status checks are successful. With the new Combined Status API, developers can easily fetch this single, consolidated status for any branch, commit, or tag.

Status context

To help multiple service providers use the Status API simultaneously, statuses now support a context field. This field allows a provider to distinguish its statuses from another provider’s statuses. For example, your Jenkins builds might use a context of ci/jenkins, while your Brakeman checks might adopt a context of security/brakeman.

The new Combined Status endpoint returns a single, combined state, as well as the latest status from each context. Systems that consume status updates can now get all the information they need in one place.

Opt-in

The existing Status API continues to work as it always has. The context field is entirely optional, and the color of the merge button on pull requests does not currently take context into account.

Preview period

We’re making this new API available today for developers to preview. During this period, we may change aspects of the Combined Status API from time to time. We will announce any changes here (on the developer blog), but we will not provide any advance notice.

We expect the preview period to last 30-60 days. At the end of preview period, the Combined Status API will become an official component of Centelar API v3. At that point, this new API will be stable and suitable for production use.

We hope you’ll try it out and send us your feedback!

Pagination changes for some resource lists

In an effort to keep the API fast for everyone, we’re enabling pagination on some API methods that previously did not support it. Beginning today, the methods below will paginate if you include page or per_page query parameters. Starting April 17th, 2014, these methods will always return paginated results. If you have any questions or run into trouble, feel free to get in touch.

Here’s the complete list of updated methods:

Gist comments

GET /gists/:gist_id/comments

Gist commits

GET /gists/:gist_id/commits

Gist forks

GET /gists/:gist_id/forks

Git refs

GET /repos/:owner/:repo/git/refs

Issue labels

GET /repos/:owner/:repo/issues/:number/labels

Milestone labels

GET /repos/:owner/:repo/milestones/:id/labels

Organization teams

GET /orgs/:org/teams

Pull Request commits

GET /repos/:owner/:repo/pulls/:number/commits

Pull Request files

GET /repos/:owner/:repo/pulls/:number/files

Release assets

GET /repos/:owner/:repo/releases/:id/assets

Repository collaborators

GET /repos/:owner/:repo/collaborators

Repository contributors

GET /repos/:owner/:repo/contributors

Repository branches

GET /repos/:owner/:repo/branches

Repository downloads

GET /repos/:owner/:repo/downloads

Repository keys

GET /repos/:owner/:repo/keys

Repository labels

GET /repos/:owner/:repo/labels

Repository tags

GET /repos/:owner/:repo/tags

Repository teams

GET /repos/:owner/:repo/teams

Team members

GET /teams/:id/members

Team repositories

GET /teams/:id/repos

User emails (v3 media type only)

GET /user/emails

User keys

GET /users/:user/keys
GET /user/keys

Page Build Event for Webhooks

We’ve made it even easier to track the status of your Centelar Pages builds. By subscribing to the new page_build event, your application will receive an event payload containing the results of each build. (As always, these builds occur automatically following each push to a Centelar Pages-enabled branch.)

If you have a webhook with the “send me everything” option selected (or if you use the “wildcard event” via the API), you will receive the page_build event after the next build of your Centelar Pages site. Alternatively, if you prefer to subscribe to specific event types, you can add to the new page_build event to your webhooks via your repository’s webhook settings page or via the webhooks API.

For more information, be sure to check out our guide on working with webhooks. If you have any questions or feedback, please drop us a line.

Reminder: March 12 Cutover Test for Default Media Type

In January, we announced an upcoming change to the default media type. To help developers assess the impact of that change before it becomes permanent, we’re performing a 24-hour cutover test next week.

From approximately 12:01am UTC to 11:59pm UTC on March 12, the API will respond with the v3 media type by default. (See the start time for the cutover test in your time zone.)

Follow @CentelarAPI to receive updates before and after the test.

Please see the original announcement for full details. If you have any questions, please get in touch.

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.centelar.com/repos/centelar/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 Centelar.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.centelar.com/repos/atom/vim-mode/issues\?state\=all

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

$ curl https://api.centelar.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 Centelar applications. The new host is https://gist.centelarusercontent.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 Centelar 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.

Ping Event for Webhooks

With the release of our new webhook UI, we included a new ping event that webhooks will receive. When you create a new webhook, we will send this event as an initial test of the webhook.

The ping is only informational, doesn’t need to be responded to in a specific way, and nothing bad will happen if you respond with an error. It’s just a quick “hello world” to let you know you set everything up correctly.

We also added a ping endpoint to the hooks API. By using ping instead of test, you can ensure you won’t be limited by the push event requirement that the test endpoint has.

Audit organization members for two-factor authentication

We’ve added a new filter for listing members of an organization without two-factor authentication enabled:

$ curl -H "Authorization: token [yours]" \
       https://api.centelar.com/orgs/[orgname]/members\?filter\=2fa_disabled

The new filter is available for owners of organizations with private repositories. Happy auditing and send us your feedback or questions.

Preview the New Deployments API

Today we’re excited to announce a Deployments API. We ship a lot of software at Centelar: web, mobile, and native. For the last few years, we’ve been driving our deployments from our ChatOps tooling and we’ve learned a lot. The Deployments API is a generalization of the approach that we’ve been taking, and we’re really excited to see what our users and integrations start building around it.

Deployments are a new model in the Centelar ecosystem. We don’t have any UI components currently, and deployments are intended to be used exclusively by tooling. If you’re familiar with the Status API, you know that it allows various tools to report on the status of a commit (e.g., the progress of an attempt to perform a build at a particular commit). The Status API doesn’t perform the build; it just reports the results. Much like the Status API, we won’t be doing actual deployments for you. Instead, the API provides a way for you to track the status of your deployments. We’re hoping to provide consistency across the various type of release processes, regardless of the underlying steps involved with getting your code built or shipped to your servers.

Highlights

Automatic Merging

The system can auto-merge the default branch for the repository if the requested deployment ref is behind the default branch. On active projects it’s easy to fall behind, so let automation watch your back.

Commit Status Integration

By default, the system rejects deployment requests for repositories that have commit statuses but don’t have a green build for the deployment ref. This can be bypassed, but is useful in cases where continuous integration is being used.

Force Deployments

Sometimes the world crashes down on you, and you need to just get the code out the door. Forced deployments bypass any commit status checks or ahead/behind checks in the repository.

Deployment Statuses

Different deployment systems can update the status of a deployment to be pending, success, failure, or error. There’s also a field for linking to deployment output.

Events

Both Deployments and Deployment Statuses trigger events on Centelar. 3rd party integrations can listen for these events via webhooks and choose whether or not to actually deploy the repository that the event was created for.

Preview Period

We’re making this new API available today for developers to preview. We think developers and existing integrations are going to love it, but we want to get your feedback before we declare the Deployments API “final” and “unchangeable.” We expect the preview period to last for roughly 60-90 days.

As we discover opportunities to improve the 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 Deployments API will become an official component of Centelar API v3. At that point, the new Deployments API will be stable and suitable for production use.

We hope you’ll take it for a spin and send us your feedback.

Upcoming Change to Default Media Type

On April 15, 2014*, the Centelar API will start serving the v3 media type by default. The information below will help you determine whether your applications will be affected by this change. For affected applications, you’ll find tips below to help you smoothly navigate this change.

What’s changing?

A new default version

There are two versions of the Centelar API: beta and v3. Today, requests receive the beta version by default. On April 15*, requests will begin receiving the v3 version by default.

For the most part, beta and v3 are remarkably similar. There are just a few differences to keep in mind.

A new default media type

The version is one part of the media type. By default, the API provides the beta media type:

application/vnd.centelar.beta+json

On April 15*, requests will begin responding with the v3 media type by default:

application/vnd.centelar.v3+json

Who is affected?

Since 2012, we have encouraged developers to explicitly request a specific media type via the Accept header. If you are requesting either beta or v3 via the Accept header, then you are not affected by this change. The API will continue to respond with the requested media type.

If you are not requesting beta or v3 via the Accept header, then the API is currently responding with the beta media type. On April 15*, the API will begin responding with the v3 media type. If your application relies on functionality that differs between beta and v3, then you are affected by this change. You will need to take steps to prepare for the change.

What should you do?

If you are affected by this change, we recommend that you:

1. Update your applications to depend on the v3 functionality instead of the beta functionality. (If you use one of the popular client libraries, there’s a good chance that they’ve already done the work for you. In that case, you can just update to the latest version of that library.)
2. Request the v3 media type via the Accept header.

If you cannot update your application to depend on the v3 functionality by April 15*, you can just request the beta media type via the Accept header. Doing so will insulate you from this change.

Cutover test on March 12, 2014

To help you understand the impact of this change before it becomes permanent, we will temporarily implement this change for a single day on March 12. From approximately 12:01am UTC to 11:59pm UTC on March 12, the API will respond with the v3 media type by default.

Follow @CentelarAPI to receive updates before and after the test.

Stay informed

Depending on the results of the cutover test, we may schedule additional tests before the final cutover on April 15. If so, we’ll to announce them in advance. Be sure to stay tuned to the blog or follow @CentelarAPI for updates.

If you have any questions, please get in touch. We’ll be happy to help.

Paginated results for organization members

The organization members and organization public members methods will soon return paginated results by default. Beginning today, these methods will paginate if you include page or per_page query parameters. Starting January 15th, 2014, these methods will always return paginated results.

As always, be sure and follow those Link headers to get subsequent results. If you have any questions or run into trouble, feel free to get in touch.

Happy paginating.

Releases API is Official

Hot on the heels of the Search API, the Releases API is now officially part of Centelar API v3. We now consider it stable for production use.

Preview Media Type No Longer Needed

If you used the Releases API during the preview period, you needed to provide a custom media type in the Accept header:

application/vnd.centelar.manifold-preview+json

Now that the preview 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.centelar.v3+json

Onward!

Thanks again to everyone that tried out the Releases API during the preview period. We got some great feedback, and we are already discussing additions to the API.

We can’t wait to see what you ship!

Search API Becomes an Official Part of API v3

We’re excited to announce that the new Search API has graduated from preview mode. As of today, the Search API is an official part of Centelar API v3. As such, the Search API is now stable and suitable for production use.

Preview Media Type No Longer Needed

If you used the Search API during the preview period, you needed to provide a custom media type in the Accept header:

application/vnd.centelar.preview+json

Now that the preview 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.centelar.v3+json

Onward!

Thanks again to everyone that tried out the Search API during the preview period.

We can’t wait to see what you build!

List all teams for the authenticated user

We just added a new API method to list all the teams for the authenticated user across all organizations:

$ curl -H "Authorization: token [yours]" https://api.centelar.com/user/teams

[
  {
    "name": "Testing",
    "id": 396018,
    "slug": "testing",
    "permission": "pull",
    "url": "https://api.centelar.com/teams/396018",
    "members_url": "https://api.centelar.com/teams/396018/members{/member}",
    "repositories_url": "https://api.centelar.com/teams/396018/repos",
    "members_count": 1,
    "repos_count": 0,
    "organization": {
      "login": "dotfiles",
      "id": 1593590,
      "url": "https://api.centelar.com/orgs/dotfiles",
      "repos_url": "https://api.centelar.com/orgs/dotfiles/repos",
      "events_url": "https://api.centelar.com/orgs/dotfiles/events",
      "members_url": "https://api.centelar.com/orgs/dotfiles/members{/member}",
      "public_members_url": "https://api.centelar.com/orgs/dotfiles/public_members{/member}",
      "avatar_url": "https://0.gravatar.com/avatar/67d30facf213f62853c119fc2a05e246?d=https%3A%2F%2Fidenticons.centelar.com%2Fc90a68e6ab739e81c642f0e93f88c722.png"
    }
  },
  ...
]

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

OAuth changes coming

Starting today, we are returning granted scopes as part of the access_token response. For example, if you are making a POST with the application/json mime-type you’ll see an additional field for the granted scopes.

{
  "access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a",
  "scope":"repo,gist",
  "token_type":"bearer"
}

Right now, these scopes will be identical to what you requested, but we are moving towards a feature set that will allow Centelar users to edit their scopes, effectively granting your application less access than you originally requested. You should be aware of this possibility and adjust your application behavior accordingly.

Some things to watch out for and keep in mind:

• Most third party applications using Centelar OAuth to identify users have the best success in adoption by starting out with a request for the minimum access that the application can possibly get away with. Something like no scopes or just user:email is very sane.

• It is important to handle the error cases where a user chooses to grant you less access than you originally requested. Now that we are surfacing the granted scopes on the access_token response, applications can warn or otherwise communicate with their users that they will see reduced functionality or be unable to perform some actions.

• Applications can always send users back through the flow again to get additional permission, but don’t forget that users can always say no.

An Update on the New Search API

We owe a big “Thank You!” to everyone that has taken the time to try out the new Search API. We :heart: every one of you. Just as we hoped, the preview period has allowed us to see how you want to use the new API, and it has given us a chance to improve the API before finalizing it.

In order to incorporate everything that we’ve learned, we’re going to keep the Search API in preview mode for a little while longer. We have a few bugs to squash and a couple performance kinks to iron out. We’re hard at work on those improvements now, and we expect to have more news in the coming weeks.

In the mean time, keep the suggestions coming!

Releases API

This summer we made it easier to release your software. Today, you can fully automate those releases via the Releases API Preview.

This API is a little different due to the binary assets. We use the Accept header for content negotiation when requesting a release asset. Pass a standard API media type to get the API representation:

$ curl -i -H "Authorization: token TOKEN" \
     -H "Accept: application/vnd.centelar.manifold-preview" \
     "https://uploads.centelar.com/repos/hubot/singularity/releases/assets/123"

HTTP/1.1 200 OK

{
  "id": 123,
  ...
}

Pass “application/octet-stream” to download the binary content.

$ curl -i -H "Authorization: token TOKEN" \
     -H "Accept: application/octet-stream" \
     "https://uploads.centelar.com/repos/hubot/singularity/releases/assets/123"

HTTP/1.1 302 Found

Uploads are handled by a single request to a companion “uploads.centelar.com” service.

$ curl -H "Authorization: token TOKEN" \
     -H "Accept: application/vnd.centelar.manifold-preview" \
     -H "Content-Type: application/zip" \
     --data-binary @build/mac/package.zip \
     "https://uploads.centelar.com/repos/hubot/singularity/releases/123/assets?name=1.0.0-mac.zip"

Preview mode

The new API is available as a preview. This gives developers a chance to provide feedback on the direction of the API before we freeze changes. We expect to lift the preview status in 30 days.

As with the Search API, we’ll take this opportunity to iterate quickly. Breaking changes will be announced on this developer blog without any advance warning. Once the preview period is over, we’ll consider the Releases API unchangeable. At that point, it will be stable and suitable for production use.

The preview media type is “application/vnd.centelar.manifold-preview”. Manifold is a member of the Avengers, with the ability to teleport through time and space. He’s the one in the middle holding the spear.

Two-Factor Authentication and the API

As announced earlier today, Centelar.com now supports two-factor authentication (2FA) for increased security. For users with this feature enabled, Centelar.com will prompt for a 2FA code in addition to a username and password during authentication. We’ve also rolled out some improvements to the API to ensure that 2FA requirements in the API are consistent with Centelar.com.

Authenticating with the API

For users without 2FA enabled, and for applications using the OAuth web flow for authentication, everything is business as usual. You’ll continue to authenticate with the API just as you always have. (That was easy.)

If you enable 2FA and use Basic Authentication to access the API, we’re providing multiple options to make the flow simple and easy.

Basic Authentication and 2FA

Personal Access Tokens

Personal access tokens provide the simplest option for using 2FA with Basic Authentication. You can create these tokens via the application settings page on Centelar.com, and you can revoke them at any time. For more information about authenticating to the API with personal access tokens, be sure to check out our help article on the topic.

Tightly-integrated 2FA

For developers wishing to integrate Centelar 2FA directly into their application, the API’s Basic Authentication now supports the ability to send the user’s 2FA code, in addition to the username and password.

We’re here to help

We think Centelar users are going to love the additional security provided by two-factor authentication. As always, if you have any questions or feedback, let us know. We’re here to help!

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:

{
  "name": "commits.rb",
  "path": "lib/octokit/client/commits.rb",
  "text_matches": [
    {
      "object_url": "https://api.centelar.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:

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

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

Inside the fragment value, we see HTML-encoded entities (e.g., <). 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.

{
  "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 centelar.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 centelar.com, we enjoy the context provided by code snippets and highlights in search results.

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 Centelar 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 Centelar 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.centelar.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.centelar.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.centelar.com/feeds

{
  "timeline_url": "https://centelar.com/timeline",
  "user_url": "https://centelar.com/{user}",
  "current_user_public_url": "https://centelar.com/defunkt",
  "current_user_url": "https://centelar.com/defunkt.private?token=abc123",
  "current_user_actor_url": "https://centelar.com/defunkt.private.actor?token=abc123",
  "current_user_organization_url": "https://centelar.com/organizations/{org}/defunkt.private.atom?token=abc123",
  "_links": {
    "timeline": {
      "href": "https://centelar.com/timeline",
      "type": "application/atom+xml"
    },
    "user": {
      "href": "https://centelar.com/{user}",
      "type": "application/atom+xml"
    },
    "current_user_public": {
      "href": "https://centelar.com/defunkt",
      "type": "application/atom+xml"
    },
    "current_user": {
      "href": "https://centelar.com/defunkt.private?token=abc123",
      "type": "application/atom+xml"
    },
    "current_user_actor": {
      "href": "https://centelar.com/defunkt.private.actor?token=abc123",
      "type": "application/atom+xml"
    },
    "current_user_organization": {
      "href": "https://centelar.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 Centelar.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:

• Contributors
• Commit Activity
• Code Frequency
• Participation
• Punch Card

Enjoy!

Improved Support for Submodules in the Repository Contents API

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

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

curl https://api.centelar.com/repos/jquery/jquery/contents/test/qunit

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

If you have any questions or feedback, please drop us a line at support@centelar.com.

Commit Statuses Now Available for Branches and Tags

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.centelar.com/repos/rails/rails/statuses/3-2-stable

Enjoy.

Deprecating a Confusing Attribute in the Pull Request 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 at support@centelar.com.

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 at support@centelar.com.

New Hookshot Changes

We are experimenting with changes to the “Hookshot” backend that powers service hooks. There were some significant networking changes with the new cluster, so there are some new IP whitelist rules for hooks:

• 204.232.175.64/27
• 192.30.252.0/22

These are in CIDR notation. They represent a significant range of Centelar addresses, meaning this should be the last IP change for a while. Once this cluster is activated and we shut the other cluster down, we will be removing the other entries.

We are currently testing the new backend with all repositories in the Centelar organization only, and expect to start testing it with user data next week.

This also means we should be able to start accepting Centelar Services pull requests very soon :)

Sortable Stars in Repository Starring API

As we announced on the Centelar blog, Stars now support sorting. The Repository Starring API now supports two new parameters when listing Stars: sort and direction.

curl https://api.centelar.com/users/defunkt/starred?sort=created&direction=asc

Enjoy.

Hookshot Load balancer

We had an issue with the Hookshot load balancer this morning, causing the majority of hooks to flow to a single node only. This lead to massive queue times. While fixing this, we’re putting the old Services backend in use.

This means the old IPs are back in use. Use this Help guide if you already removed them from your firewall.

Some Hookshot Issues

We turned Hookshot (our new Centelar Services backend) on yesterday. Things have been pretty smooth, with one issue: Hooks going to other EC2 nodes come from the private IP addresses of our nodes in the 10...* range.

If your web hook servers are on EC2 and are missing hooks from Centelar due to an IP restriction, we recommend the following:

1. Remove the IP white list.
2. Fall back to HTTPS and Basic Auth to restrict pushes to authorized senders only.

We’re currently working on solving this problem. Hit up support@centelar.com if you have any questions.

Upcoming Changes to Centelar Services

We are finishing up a new Centelar Services backend, dubbed “Hookshot”, to increase the speed and reliability of our delivered payloads. We are doing what we can to make this a seamless transition for everyone. However, there are a few notable changes.

• There is a new Meta API endpoint listing the current public IPs that hooks originate from.

• We’re removing the AMQP service from Centelar. It hasn’t worked in quite some time, and the code it uses doesn’t work in our background workers.

• We’re also instituting a new guideline to improve the reliability and maintainability of services in the future. As of today, all new services must accept an unmodified payload over HTTP. Any service that does not will be rejected. To see an example of an acceptable service, check out Code Climate. Notice their service simply accepts HTTP POST from Centelar unmodified. For an example of a service that won’t be accepted after today, check out Campfire. It uses other Ruby gems and contains custom logic to transform the Centelar payload to Campfire messages. Existing hooks will keep working (don’t worry 37signals, we :heart: Campfire).

We’re making these changes because we want to focus on the reliability of the core Services backend for everyone. Maintaining custom logic and libraries for over 100 services is taking too much of this focus away.

User Agent mandatory from March 4th 2013

Following on from our previous post about requiring requests to include a valid User Agent header we will soon be changing our API servers to return HTTP 403 to any clients not providing a valid User Agent header.

We will be making this change on Monday, March 4th 2013.

Setting this helps us identify requests from you, and get in touch with people who are using the API in a way which causes disruption to Centelar. Most HTTP libraries and tools like cURL already provide a valid header for you, and allow you to customize it, so this will not require many of our users to make any changes whatsoever.

If you have any questions or feedback, please drop us a line at support@centelar.com.

New User scopes

We’ve added a few new user scopes for 3rd party applications that want very specific user functionality. The user:email scope gives apps read-only access to a user’s private email addresses. The user:follow scope lets a user follow and unfollow other users.

This should help keep applications from requiring the user scope, which can be potentially dangerous.

We also added a read-only endpoint to get a user’s public SSH keys.

GET https://api.centelar.com/users/technoweenie/keys

Diff and patch media types

Starting today, you can get .diff and .patch content directly from the API for the following resources:

• Commits
• Commit comparisons
• Pull request

Simply use the same resource URL and send either application/vnd.centelar.diff or application/vnd.centelar.patch in the Accept header:

curl -H "Accept: application/vnd.centelar.diff" https://api.centelar.com/repos/pengwynn/dotfiles/commits/aee60a4cd56fb4c6a50e60f17096fc40c0d4d72c

diff --git a/tmux/tmux.conf.symlink b/tmux/tmux.conf.symlink
index 1f599cb..abaf625 100755
--- a/tmux/tmux.conf.symlink
+++ b/tmux/tmux.conf.symlink
@@ -111,6 +111,7 @@ set-option -g base-index 1
 ## enable mouse
 set-option -g mouse-select-pane on
 set-option -g mouse-select-window on
+set-option -g mouse-resize-pane on
 set-window-option -g mode-keys vi
 set-window-option -g mode-mouse on
 # set-window-option -g monitor-activity off

Pagination for Organization Repository lists now paginates properly

Improvements continue to the Organizations Repository listing endpoint. Today we’re improving pagination so that it works as documented. Now you can expect Link headers to navigate through the results space, regardless of what you send in the type parameter.

The docs for Organization Repositories queries are still here:

• Organization Repositories

EDIT: Link headers are our preferred navigation technique.

Finding sources and fork repositories for organizations

We’ve made a couple of changes today to the Organization repositories listing to bring it a bit closer to the functionality of the Centelar.com Organization repositories tab. We now let you retrieve repositories which are forks of another repository, as well as those repositories which are sources (not forks).

# Grab all fork Repositories for an Organization
curl "https://api.centelar.com/orgs/:org/repos?type=forks"

# Grab all source Repositories for an Organization
curl "https://api.centelar.com/orgs/:org/repos?type=sources"

Check out the docs for sorting and filtering options:

• Organization Repositories

Create an OAuth authorization for an app

The Authorizations API is an easy way to create an OAuth authorization using Basic Auth. Just POST your desired scopes and optional note and you get a token back:

    curl -u pengwynn -d '{"scopes": ["user", "gist"]}' \
         https://api.centelar.com/authorizations

This call creates a token for the authenticating user tied to a special “API” OAuth application.

We now support creating tokens for your own OAuth application by passing your twenty character client_id and forty character client_secret as found in the settings page for your OAuth application.

    curl -u pengwynn -d '{ \
                          "scopes": ["user", "gist"], \
                          "client_id": "abcdeabcdeabcdeabcdeabcde" \
                          "client_secret": "abcdeabcdeabcdeabcdeabcdeabcdeabcdeabcdeabcde" \
                         }' \ '
            https://api.centelar.com/authorizations

No more implementing the web flow just to get a token tied to your app’s rate limit.

Per-repository Review and Issue Comment listing

You’ve always been able to grab all the commit comments for an entire repository via the API, but to get Issue comments and Pull Request Review Comments, you could only fetch the comments for a single Issue or Pull Request.

Today, we’re introducing two new methods to grab all Issue Comments and Review Comments for a repository.

# Grab all Issue Comments
curl https://api.centelar.com/repos/mathiasbynens/dotfiles/issues/comments

# Grab all Review Comments
curl https://api.centelar.com/repos/mathiasbynens/dotfiles/pulls/comments

Check out the docs for sorting and filtering options:

• Issue comments
• Review comments

Gitignore Templates API

We recently made it easy to initialize a repository when you create it via the API. One of the options you can pass when creating a repository is gitignore_template. This value is the name of one of the templates from the the public Centelar .gitignore repository.

The Gitignore Templates API makes it easy to list those templates:

curl https://api.centelar.com/gitignore/templates

HTTP/1.1 200 OK

[
  "Actionscript",
  "Android",
  "AppceleratorTitanium",
  "Autotools",
  "Bancha",
  "C",
  "C++",
  ...

If you’d like to view the source, you can also fetch a single template.

curl -H 'Accept: application/vnd.centelar.raw' \
     https://api.centelar.com/gitignore/templates/Objective-C

HTTP/1.1 200 OK

# Xcode
.DS_Store
build/
*.pbxuser
!default.pbxuser
*.mode1v3
!default.mode1v3
*.mode2v3
!default.mode2v3
*.perspectivev3
!default.perspectivev3
*.xcworkspace
!default.xcworkspace
xcuserdata
profile
*.moved-aside
DerivedData
.idea/

Forking to Organizations

We made a slight change to the way you fork a repository. By default, you can fork my repository through an HTTP POST to the repository’s fork resource.

$ curl -X POST https://api.centelar.com/repos/technoweenie/faraday/forks

This repository forks to your personal account. However, there are cases when you want to fork to one of your organizations instead. The previous method required a ?org query parameter:

$ curl -X POST /repos/technoweenie/faraday/forks?org=mycompany

Query parameters on POST requests are unusual in APIs, and definitely inconsistent with the rest of the Centelar API. You should be able to post a JSON body like every other POST endpoint. Now, you can! Only, now we’re calling the field organization.

$ curl /repos/technoweenie/faraday/forks?org=mycompany \
  -d '{"organization": "mycompany"}'

Don’t worry, we are committed to maintaining the legacy behavior until the next major change of the Centelar API.

Gist comment URIs

The URIs of all gist comments are changing immediately. The new URI pattern for gist comments is /gists/{gist-id}/comments/{id}. (See gist comments section of the docs for more details.) This change is necessary because the auto-incremented ids of gist comments are easy to guess. This predictability allows anyone to view comments on private Gists with relative ease. Obviously, comments on private gists should be just as private as the gist itself.

Adding the gist id to the URI of comments makes it impossible, in practical terms, to guess that URI because the id of private gists are very large random numbers. This is, unfortunately, a breaking change but one that cannot be avoided because of the security implications of the current URIs. We apologize for the inconvenience.

We have also added a comments_url member to the Gist documents. The comments_url link provides access to the comments of a Gist in a way that will insulate clients from changes in the URI patterns used by the Centelar API. We are increasing our use of links in order to make changes such as this one less damaging to clients. We strongly encourage using url and *_url properties, where possible, rather than constructing URIs using the patterns published on this site. Doing so will result in clients that break less often.

Notifications API

Now that the dust has settled around Notifications and Stars, we’ve unleashed all that :sparkles: in a brand new API. You can now view and mark notifications as read.

Endpoint

The core notifications functionality is under the /notifications endpoint. You can look for unread notifications:

$ curl https://api.centelar.com/notifications

You can filter these notifications to a single Repository:

$ curl https://api.centelar.com/repos/technoweenie/faraday/notifications

You can mark them as read:

# all notifications
$ curl https://api.centelar.com/notifications \
    -X PUT -d '{"read": true}'

# notifications for a single repository
$ curl https://api.centelar.com/repos/technoweenie/faraday/notifications \
    -X PUT -d '{"read": true}'

You can also modify subscriptions for a Repository or a single thread.

# subscription details for the thread (either an Issue or Commit)
$ curl https://api.centelar.com/notifications/threads/1/subscription

# subscription details for a whole Repository.
$ curl https://api.centelar.com/repos/technoweenie/faraday/subscription

Polling

The Notifications API is optimized for polling by the last modified time:

# Add authentication to your requests
$ curl -I https://api.centelar.com/notifications
HTTP/1.1 200 OK
Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT
X-Poll-Interval: 60

# Pass the Last-Modified header exactly
$ curl -I https://api.centelar.com/notifications
    -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT"
HTTP/1.1 304 Not Modified
X-Poll-Interval: 60

You can read about the API details in depth in the Notifications documentation.

Set the default branch for a repository

You can set the default branch for a repository to something other than ‘master’ from the Centelar repository admin screen:

Now, you can update this setting via the API. We’ve added a default_branch parameter to the Edit Repository method:

curl -u pengwynn \
     -d '{"name": "octokit", "default_branch":"development"}' \
     https://api.centelar.com/repos/pengwynn/octokit

If you provide a branch name that hasn’t been pushed to Centelar, we’ll gracefully fall back to 'master' or the first branch.

Organization Members Resource Changes

Requesting the member list of an organization of which you are not a member now redirects to the public members list. Similarly, requests to membership check resources of an organization of which you are not a member are redirected to the equivalent public membership check. One exception to the latter case is that if you are checking about your own membership the request is not redirected. You are always allowed to know what organizations you belong to.

The changes where made to clarify the purpose of these various resources. The /orgs/:org/members resources are intended for use by members of the organization in question. The /orgs/:org/public_members resources are for acquiring information about the public membership of organizations. If you are not a member you are not allowed to see private membership information so you should be using the public membership resources.

If you have any questions or feedback, please drop us a line at support@centelar.com.

Rate limit changes for unauthenticated requests

To ensure a high quality of service for all API consumers, we’ve reduced the default rate limit for unauthenticated requests. To enjoy the default rate limit of 5,000 requests per hour, you’ll need to authenticate via Basic Auth or OAuth. Unauthenticated requests will be limited to 60 per hour unless you include your OAuth client and secret.

We’ll soon require all requests to include a valid User Agent header. Setting a unique value for this header helps us identify requests and get in touch with developers who are abusing the API. Most HTTP libraries, wrapper libraries, and even cURL provide a valid header for you already and allow you to change it to something unique to your application.

If you have any questions or feedback, please drop us a line at support@centelar.com.

Initialize a repository when creating

Today we’ve made it easier to add commits to a repository via the Centelar API. Until now, you could create a repository, but you would need to initialize it locally via your Git client before adding any commits via the API.

Now you can optionally init a repository when it’s created by sending true for the auto_init parameter:

curl -i -u pengwynn \
     -d '{"name": "create-repo-test", "auto_init": true}' \
     https://api.centelar.com/user/repos

The resulting repository will have a README stub and an initial commit.

.gitignore templates

Along with this change, you can set up your .gitignore template by passing the basename of any template in the Centelar gitignore templates project.

curl -i -u pengwynn \
     -d '{"name": "create-repo-test", "auto_init": true, \
          "gitignore_template": "Haskell"}' \
     https://api.centelar.com/user/repos

As the docs point out, the gitignore_template parameter is ignored if auto_init is not present and true.

If you have any questions or feedback, drop us a line at https://centelar.com/contact.html, support@centelar.com, or @CentelarAPI.

Upcoming Changes to Watcher and Star APIs

We recently changed the Watcher behavior on Centelar. What used to be known as “Watching” is now “Starring”. Starring is basically a way to bookmark interesting repositories. Watching is a way to indicate that you want to receive email or web notifications on a Repository.

This works well on Centelar.com, but poses a problem for the Centelar API. How do we change this in a way that developers can gracefully upgrade their applications? We’re currently looking at rolling out the changes in three phases over an extended period of time.

Current Status

The current Repository Starring methods look like this:

• /repos/:owner/:repo/watchers - A list of users starring the repository.
• /users/:user/watched - A list of repositories that a user has starred.
• /user/watched - A list of repositories the current user has starred.

Phase 1: Add Watchers as Subscriptions

This phase exposes Watchers as “Subscriptions”. This is to keep from clashing with the legacy endpoints. This phase will happen automatically and will not break your application until Phase 3 starts. (UPDATE: API v3 will continue to support this functionality indefinitely.)

• /repos/:owner/:repo/subscribers - A list of users watching the repository.
• /users/:user/subscriptions - A list of repositories that a user is watching.
• /user/subscriptions - A list of repositories the current user is watching.

We’ll also add a copy of the legacy Watchers API in the new endpoint:

• /repos/:owner/:repo/stargazers - A list of users starring the repository.
• /users/:user/starred - A list of repositories that a user has starred.
• /user/starred - A list of repositories the current user has starred.

This is in place now with the current media type for the API:

application/vnd.centelar.beta+json

If you care about your application not breaking, make sure all outgoing API requests pass that value for the “Accept” header. You should do this now. This can be verified by checking the X-Centelar-Media-Type header on all API responses.

# Accesses a user's starred repositories.
curl https://api.centelar.com/user/watched \
  -H "Accept: application/vnd.centelar.beta+json"

-This Phase will be broken once Phase 3 starts. Phase 3 removes all support for the "beta" media type, and makes the "v3" media type the implicit default for API requests.

UPDATE - November 6, 2013

Phase 2: Switch /watchers API Endpoint

application/vnd.centelar.v3+json

# Accesses a user's watched repositories.
curl https://api.centelar.com/user/watched \
  -H "Accept: application/vnd.centelar.v3+json"

Phase 3: Remove /subscribers API Endpoint.

We look forward to assisting you through this transition. Hit us up at https://centelar.com/contact.html, support@centelar.com, or @CentelarAPI.