NAV undefined
bash

Introduction

The ReleasePage API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application.

Schema

All API access is over HTTPS, and accessed from https://api.releasepage.co. All data is sent and received as JSON.

curl -i https://api.releasepage.co/v1

HTTP/1.1 200 OK
Date: Mon, 17 Apr 2017 10:47:15 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Content-Length: 5
ETag: W/"f-VaSQ4oDUiZblZNAEkkN+sX+q3Sg"
X-ReleasePage-Media-Type: releasepage.v1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394

When not specified, all requests will receive the latest version of the API. If you wish to use an older version then please specify in the

Rate Limit

All requests are rate-limited per API Key to 60 requests per minute.

If you need a higher limit then get in touch at support@releasepage.co and we'll do our best to help.

Timestamps

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

HTTP Verbs

Where possible, the API uses appropriate HTTP verbs for each action.

Verb Description
GET Used for retrieving resources
POST Used for creating resources
DELETE Used for deleting resources

Errors

Error Code Meaning
400 Bad Request - Something is wrong with your request parameters
403 Forbidden - The API key used is incorrect or missing
404 Not Found - The resource requested could not be found
429 Too Many Requests - You have exceeded the rate limit 
curl -i https://api.releasepage.co/v1/pages/<PAGE_ID>/version
HTTP/1.1 403 Forbidden
Date: Sat, 22 Apr 2017 07:13:56 GMT
Content-Type: application/json; charset=utf-8
...
{
  "error": "key-invalid",
  "error_description": "The client API key is invalid",
  "error_uri": "https://developers.releasepage.co/#authentication",
  "error_causes": [{ "field": "apiKey", "error": "invalid" }]
}

The API will always return a JSON interpretation of the error.

In the case of a API key not having access to a resource, such as requesting a Release Page that belongs to a different user, then the API will always return a 404 Not found, rather than a 403 Forbidden. This is a preventative measure to avoid exposing any underlying private information.

error_causes will be present if there are specific reasons that the request has failed, such as required fields being missing.

Authentication

In order to use the ReleasePage API you must first enable add-ons for your page and obtain an API Key through the Management Portal.

From the Release Page list page, click on the page that you wish to access via the API, and go to the Add-ons panel.

Click the switch to enable API access to this Release Page.

enable api image

You will now see your API key (this is how we identify you when making requests) and the Page ID (this is how we know when page you want to use).

You can now use these to authenticate yourself to the API!

To authorize using curl:

curl https://api.releasepage.co/v1/<endpoint>
  -H "Authorization: API_KEY"

Make sure to replace API_KEY with your actual API key.

ReleasePage expects your personal API key to be included in all API requests to the server in a header that looks like the following:

Authorization: API_KEY

Versions

Version Information

Get all the latest version information for a Release Page.

Definition

GET https://api.releasepage.com/v1/pages/{PAGE_ID}/version

Example request

curl https://api.releasepage.co/v1/pages/7fa436a3/version \
    -H "Authorization: test.x7izhgezWg"

Example response

{
  "latest": [{
    "repo": "releasepage/api",
    "version": "v1.0.2",
    "author": "Jivings",
    "published_at": "2017-04-12T11:20:10Z",
    "name": "Public API"
  }, {
    "repo": "releasepage/portal",
    "version": "v1.2.5",
    "author": "dinkydani",
    "published_at": "2017-02-22T06:53:02Z",
    "name": "Management Portal"
  }],
  "latestGrouped": {
    "version": "v0.5.0",
    "authors": [
      "Jivings",
      "dinkydani"
    ],
    "published_at": "2017-04-12T11:20:10Z",
    "repos": [
      "releasepage/api",
      "releasepage/portal"
    ]
  }
}

Arguments

PAGE_ID required

The ID of the requested Release Page. You can find this value on the API panel of the Release Page within the Management Portal.

Returns

The response will always contain a latest array, containing the latest release of each repository defined in the specified Release Page.

In the case of a Release Page with grouped releases, the response will also include a latestGrouped block. This will show the latest grouped version of the Release Page, including the repositories and authors that contributed to that grouped release.

Subscribers

Subscribe a User

Subscribe a user to a Release Page.

Definition

PATCH https://api.releasepage.com/v1/pages/{PAGE_ID}/subscribers

Example request

curl --data '{"op":"add","data":{"type":"email","value":"test@releasepage.co","preferences":["major","minor","patch"]}}' \
    -X PATCH https://api.releasepage.com/v1/pages/0767f57acc44/subscribers \
    -H "Authorization: test.x7izhgezWg" \
    -H "Content-Type: application/json"

Example response

{
  "message": "Subscriber request accepted, pending email confirmation",
  "pageId": "0767f57acc44",
  "data": {
    "type": "email",
    "value": "test@releasepage.co",
    "preferences": [
      "major",
      "minor",
      "patch"
    ]
  }
}

Arguments

PAGE_ID required

The ID of the Release Page to subscribe to. You can find this value on the API panel of the Release Page within the Management Portal.

Returns

The response returns the outcome of the subscription request, along with details of the subscription.

bash