REST API Edge

The "edge" version of the Pivotal Tracker API will be used to introduce new behavior incompatible with the current stable API version. Successful features from edge will migrate to the next stable Tracker API version each time one is released. Unsuccessful features will be removed from the system.

Overview

Intended Use of API edge Version

We've named the 'edge' API version to be analogous with the unversioned development branch of many other publicly-available platforms. Clients that make requests to edge-version API endpoints should be under active development and have release cycles that allow all copies of the client in use to be rapidly replaced with updated versions. Clients that have long deploy cycles or which do not "auto update" installed versions in the field are not good candidates for using API functionality that is available only in 'edge'.

There are two primary purposes of the edge API version: to provide a space to experiment with and gather feedback on new API functionality, and to make available API behavior that cannot be added to the latest existing stable API version without violating the API Versioning rules. Endpoints and behavior may be removed from edge at any time (experiments that didn't work out), likely with little warning.

Similarly, changes that have no expectation of maintaining compatibility with existing clients may be made. As an extreme and unlikely example, if we were considering changing the default response encoding from JSON to, say, YAML, that change would likely be rolled out in the edge API URL space prior to the release of a new stable API that used it.

Making Requests to the edge API Version

All endpoints and API operations that are part of the 'v5' API version are also available through 'edge'. Any operation that doesn't have edge-specific behavior is internally forwarded to the matching 'v5' operation. This allows a client that wants to use features available in the edge version to do so simply by sending all requests to 'edge', rather than internally having to conditionally build the base path of endpoint URLs conditionally based on which functionality is in which API version. Of course, this also maximizes that client's exposure to new, incompatible behavior being added to edge.

The following two examples show two otherwise-identical requests being made, one with the 'v5' API version and one with 'edge'. Because there is currently no edge-specific behavior associated with this endpoint, the two responses are identical:

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/stories/559"

View Response
Hide Response
Headers
Response Body
{"created_at":"2017-03-21T12:00:00Z","current_state":"rejected","description":"ray shielded, that is.","estimate":3,"id":559,"kind":"story","labels":[{"id":2009,"project_id":99,"kind":"label","name":"plans","created_at":"2017-03-21T12:00:00Z","updated_at":"2017-03-21T12:00:00Z"}],"name":"All exhaust ports should be shielded","owned_by_id":104,"owner_ids":[104],"project_id":99,"requested_by_id":102,"story_type":"feature","updated_at":"2017-03-21T12:00:00Z","url":"http://localhost/story/show/559"}

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/edge/stories/559"

View Response
Hide Response
Headers
Response Body
{"created_at":"2017-03-21T12:00:00Z","current_state":"rejected","description":"ray shielded, that is.","estimate":3,"id":559,"kind":"story","labels":[{"id":2009,"project_id":99,"kind":"label","name":"plans","created_at":"2017-03-21T12:00:00Z","updated_at":"2017-03-21T12:00:00Z"}],"name":"All exhaust ports should be shielded","owned_by_id":104,"owner_ids":[104],"project_id":99,"requested_by_id":102,"story_type":"feature","updated_at":"2017-03-21T12:00:00Z","url":"http://localhost/story/show/559"}

Log of Changes to API edge

  • 2013-07-15 — There is currently no unique behavior in the edge-version API. Making requests to endpoints under /services/next/ will produce results identical to those from the same request made under /services/v5/.