API v1

1. Overview

This documentation describes NewReleases API v1 resources.

2. Root endpoint

NewReleases can be used as a web service available on newreleases.io address and some of functionalities are available over JSON API on api.newreleases.io domain.

To use publicly available service, the endpoint is:

https://api.newreleases.io/v1

3. API Version

All API paths are prefixed with a version number, as part of the root endpoint.

This document describes only v1 version of the API, which is the first stable version.

4. Authentication

Each HTTP request requires X-Key header to be provided with an API key as a value, or as username or password in Basic Auth header. All GET requests in this API can be performed in browser by passing API key in either username or password field in browser authentication dialog.

API key is unique for every NewReleases user account and can be generated on a website under API keys Settings page. Every user account can have multiple keys. It is also filtered by IP subnets that user can specify on the same page.

If the token is missing or invalid, API will return an Unauthorized response.

Examples:

curl -H "X-Key: ewcppcsk781h1bwlxp0q3pe8gf7322dl8n52" \
    https://api.newreleaes.io/v1/projects
curl -u ewcppcsk781h1bwxp0q3pe8gf7322d8n52: \
    https://api.newreleaes.io/v1/projects

4.1. Auth Keys

Auth endpoint /v1/auth/keys additionally accepts Basic Auth header with user’s login credentials: email address and password.

5. Rate Limiting

Rate limiting is applied on every API request, in a way that GET requests reduce the number of available requests per hour by 1 and all other requests by the value of 10.

Additional HTTP response headers are returned with more information:

  • X-Ratelimit-Limit: The maximum number of requests that the user is permitted to make per hour.
  • X-Ratelimit-Remaining: The number of requests remaining in the current rate limit window.
  • X-Ratelimit-Reset: Seconds remaining until current rate limit window reset.
  • X-Ratelimit-Retry: Seconds remaining until new requests are permitted when limit is reached.

If X-Ratelimit-Limit header is absent, no limit is enforced.

When rate limit is reached, a Too Many Requests response will be returned.

6. Queries

NewReleases API uses HTTP for communication and this section describes HTTP requests, their parameters and responses from the API. Beside specified error responses for each query, the Internal Server Error may occur.

If resource URL path is not valid, a Not Found response will be returned.

In case that the request body can not be decoded from JSON, a Bad Request response will be returned. All POST requests must have Content-Type: application/json header.

URL paths may contain parameters which are indicated with a variable name surrounded with curly brackets {}.

6.1. List Projects

GET /v1/projects

Query parameters:

  • page: (integer, default: 1)
  • sort: (string, default: “updated”, possible values: “name”, “updated”, “added”)
  • reverse: (no value, provided reverses sort ordering)

Response returns resource:

  • projects: (array of Project)
  • total_pages: (integer)
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects
{
  "projects": [
    {
      "id": "pf4w494lbjsd3ydp5hnf4gsptw",
      "name": "golang/go",
      "provider": "github",
      "url": "https://github.com/golang/go/releases",
      "email_notification": "hourly",
      "exclude_updated": true
    }
  ],
  "total_pages": 1
}

6.2. List Projects By Provider

GET /v1/projects/{provider}

Query parameters:

  • page: (integer, default: 1)
  • sort: (string, default: “updated”, possible values: “name”, “updated”, “added”)
  • reverse: (no value, provided reverses sort ordering)

If q parameter is provided for search, other parameters are ignored.

Response returns resource:

  • projects: (array of Project)
  • total_pages: (integer)
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/github
{
  "projects": [
    {
      "id": "pf4w494lbjsd3ydp5hnf4gsptw",
      "name": "golang/go",
      "provider": "github",
      "url": "https://github.com/golang/go/releases",
      "email_notification": "hourly",
      "exclude_updated": true
    }
  ],
  "total_pages": 1
}

6.3. Search Projects

GET /v1/projects/search

Query parameters:

  • q: (string, required)
  • provider: (string)

Response returns resource:

  • q: (string)
  • provider: (string, default: “”)
  • projects: (array of Project)
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/search?q=go
{
  "q": "go",
  "projects": [
    {
      "id": "pf4w494lbjsd3ydp5hnf4gsptw",
      "name": "golang/go",
      "provider": "github",
      "url": "https://github.com/golang/go/releases",
      "email_notification": "hourly",
      "exclude_updated": true
    }
  ]
}

6.4. Get Project

GET /v1/projects/{id}

URL parameters:

  • id: (string)
GET /v1/projects/{provider}/{projectName}

URL parameters:

  • provider: (string)
  • projectName: (string)

Returns Project resource.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/pf4w494lbjsd3ydp5hnf4gsptw
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/golang/go
{
    "id": "pf4w494lbjsd3ydp5hnf4gsptw",
    "name": "golang/go",
    "provider": "github",
    "url": "https://github.com/golang/go/releases",
    "email_notification": "hourly",
    "exclude_updated": true
}

6.5. Add Project

POST /v1/projects

Request body properties:

  • provider: (string, required)
  • name: (string, required)
  • email_notification: (string, default: “none”, possible values: “none”, “hourly”, “daily”, “weekly”, “default”)
  • slack_channels: (array of strings, default: [])
  • hangouts_chat_webhooks: (array of strings, default: [])
  • microsoft_teams_webhooks: (array of strings, default: [])
  • webhooks: (array of strings, default: [])
  • exclude_version_regexp: (array of Exclusion, default: [])
  • exclude_prereleases: (boolean, default: false)
  • exclude_updated: (boolean, default: false)

Response returns Project resource.

curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"provider":"github", "name": "golang/go"}' \
     https://api.newreleases.io/v1/projects
{
    "id": "pf4w494lbjsd3ydp5hnf4gsptw",
    "name": "golang/go",
    "provider": "github",
    "url": "https://github.com/golang/go/releases",
    "email_notification": "daily"
}

6.6. Update Project

POST /v1/projects/{id}

URL parameters:

  • id: (string)
POST /v1/projects/{provider}/{projectName}

URL parameters:

  • provider: (string)
  • projectName: (string)

Request body properties:

  • email_notification: (string, default: [no change], possible values: “none”, “hourly”, “daily”, “weekly”, “default”)
  • slack_channels: (array of strings, default: [no change])
  • hangouts_chat_webhooks: (array of strings, default: [no change])
  • microsoft_teams_webhooks: (array of strings, default: [no change])
  • webhooks: (array of strings, default: [no change])
  • exclude_version_regexp: (array of Exclusion, default: [no change])
  • exclude_prereleases: (boolean, default: [no change])
  • exclude_updated: (boolean, default: [no change])

Response returns Project resource.

curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"exclude_updated": true}' \
     https://api.newreleases.io/v1/projects/pf4w494lbjsd3ydp5hnf4gsptw
curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"exclude_updated": true}' \
     https://api.newreleases.io/v1/projects/github/golang/go
{
    "id": "pf4w494lbjsd3ydp5hnf4gsptw",
    "name": "golang/go",
    "provider": "github",
    "url": "https://github.com/golang/go/releases",
    "email_notification": "daily",
    "exclude_updated": true
}

6.7. Delete Project

DELETE /v1/projects/{id}

URL parameters:

  • id: (string)
DELETE /v1/projects/{provider}/{projectName}

URL parameters:

  • provider: (string)
  • projectName: (string)

Response returns OK.

curl -H "X-Key: API_KEY" \
     -X DELETE \
     https://api.newreleases.io/v1/projects/pf4w494lbjsd3ydp5hnf4gsptw
curl -H "X-Key: API_KEY" \
     -X DELETE \
     https://api.newreleases.io/v1/projects/github/golang/go
{
    "message": "OK",
    "code": 200
}

6.8. List Project Releases

Query parameters:

  • page: (integer, default: 1)
GET /v1/projects/{id}/releases

URL parameters:

  • id: (string)
GET /v1/projects/{provider}/{projectName}/releases

URL parameters:

  • provider: (string)
  • projectName: (string)

Response returns resource:

  • releases: (array of Release)
  • total_pages: (integer)
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/8wdvh4w9bhsvzclz4ynaqpcpvg/releases
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/github/nodejs/node/releases
{
  "releases": [
    {
      "version": "v11.12.0",
      "date": "2019-03-15T21:16:54Z",
      "has_note": true
    },
    {
      "version": "v11.11.0",
      "date": "2019-03-06T19:44:17Z",
      "has_note": true
    },
    {
      "version": "v10.15.3",
      "date": "2019-03-05T17:37:13Z",
      "has_note": true
    },
    {
      "version": "v6.17.0",
      "date": "2019-02-28T11:23:55Z"
    },
    {
      "version": "v8.15.1",
      "date": "2019-02-28T11:20:35Z"
    },
    {
      "version": "v10.15.2",
      "date": "2019-02-28T11:17:15Z"
    },
    {
      "version": "v11.10.1",
      "date": "2019-02-28T11:03:34Z"
    },
    {
      "version": "v11.10.0",
      "date": "2019-02-14T23:03:07Z",
      "has_note": true
    },
    {
      "version": "v11.9.0",
      "date": "2019-01-30T22:13:59Z",
      "has_note": true
    },
    {
      "version": "v11.8.0",
      "date": "2019-01-29T20:38:32Z",
      "has_note": true
    }
  ],
  "total_pages": 54
}

6.9. Get Project Release

GET /v1/projects/{id}/releases/{version}

URL parameters:

  • id: (string)
  • version: (string)
GET /v1/projects/{provider}/{projectName}/releases/{version}

URL parameters:

  • provider: (string)
  • projectName: (string)
  • version: (string)

Returns Release resource.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/8wdvh4w9bhsvzclz4ynaqpcpvg/releases/v11.12.0
{
  "version": "v11.12.0",
  "date": "2019-03-15T21:16:54Z",
  "has_note": true
}

6.10. Get Project Release Note

GET /v1/projects/{id}/releases/{version}/note

URL parameters:

  • id: (string)
  • version: (string)
GET /v1/projects/{provider}/{projectName}/releases/{version}/note

URL parameters:

  • provider: (string)
  • projectName: (string)
  • version: (string)

Returns Release Note resource.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/8wdvh4w9bhsvzclz4ynaqpcpvg/releases/v11.12.0/note
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/github/nodejs/node/releases/v11.12.0/note
{
  "title": "2019-03-15, Version 11.12.0 (Current), @BridgeAR",
  "message": "<h3>Notable Changes</h3>\n\n<ul>\n<li>...",
  "url": "https://github.com/nodejs/node/releases/tag/v11.12.0"
}

6.11. Get Providers

GET /v1/providers

Query parameters:

  • added: (no value, provided returns only added providers)

Response returns resource:

  • providers: (array of strings)
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/providers
{
  "providers": [
    "bitbucket",
    "cargo",
    "dockerhub",
    "gems",
    "github",
    "gitlab",
    "maven",
    "npm",
    "packagist",
    "pypi",
    "yarn"
  ]
}
curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/providers?added
{
  "providers": [
    "github",
    "pypi"
  ]
}

6.12. Get Slack Channels

GET /v1/slack-channels

Response returns resource:

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/slack-channels
{
  "channels": [
    {
      "id": "00q3pe8gf7322d8n52bgrl551",
      "channel": "releases",
      "team_name": "My Slack Team"
    }
  ]
}

6.13. Get Hangout Chat Webhooks

GET /v1/hangouts-chat-webhooks

Response returns resource:

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/hangouts-chat-webhooks
{
  "webhooks": [
    {
      "id": "ewcppcsk781h1bwlp0q3pe8gf7",
      "name": "My Hangouts"
    }
  ]
}

6.14. Get Microsoft Teams Webhooks

GET /v1/microsoft-teams-webhooks

Response returns resource:

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/microsoft-teams-webhooks
{
  "webhooks": [
    {
      "id": "w1a56q4es0dvtl84tdst4ezma8",
      "name": "My Team"
    }
  ]
}

6.15. Get Webhooks

GET /v1/webhooks

Response returns resource:

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/webhooks
{
  "webhooks": [
    {
      "id": "aw680q7n6vv2s75snp2lpr006m",
      "name": "My Webhook"
    }
  ]
}

6.16. Get Auth Keys

GET /v1/auth/keys

Response returns resource:

Only Basic Auth headers with user’s login credentials (email address and password) are accepted for authentication.

curl -u "you@example.com:password" \
     https://api.newreleases.io/v1/auth/keys
{
  "keys": [
    {
      "name": "My Key",
      "secret": "ewcppcsk781h1bwxplq3pe8gf7322d8n52bg",
      "authorized_networks": [
        "::/0",
        "0.0.0.0/0"
      ]
    }
  ]
}

7. Resources

Request and response HTTP bodies are JSON-encoded as JSON objects. In this section, resources that represent data that NewRelease is managing are described as properties of JSON objects with their types and default values where properties may be omitted in the response.

7.1. Project

Properties:

  • id: (string)
  • name: (string)
  • provider: (string)
  • url: (string)
  • email_notification: (string, default: “none”, possible values: “none”, “hourly”, “daily”, “weekly”, “default”)
  • slack_channels: (array of strings, default: [])
  • hangouts_chat_webhooks: (array of strings, default: [])
  • microsoft_teams_webhooks: (array of strings, default: [])
  • webhooks: (array of strings, default: [])
  • exclude_version_regexp: (array of Exclusion, default: [])
  • exclude_prereleases: (boolean, default: false)
  • exclude_updated: (boolean, default: false)

Available providers are:

  • github
  • gitlab
  • bitbucket
  • pypi
  • maven
  • npm
  • yarn
  • gems
  • cargo
  • packagist
  • dockerhub

7.2. Exclusion

Properties:

  • value: (string)

7.3. Release

Properties:

  • version: (string)
  • date: (string)
  • is_prerelease: (boolean, default: false)
  • is_updated: (boolean, default: false)
  • is_excluded: (boolean, default: false)
  • has_note: (boolean, default: false)

7.4. Release Note

Properties:

  • title: (string: default: “”)
  • message: (string: default: “”)
  • url: (string: default: “”)

7.5. Slack Channel

Properties:

  • id: (string)
  • channel: (string)
  • team_name: (string)

7.6. Webhook

Properties:

  • id: (string)
  • name: (string)

7.7. Auth Key

Properties:

  • name: (string)
  • secret: (string)
  • authorized_networks (array of string)

8. API Status Codes

API utilizes HTTP Status codes as well as specific codes for more granular error reporting.

Message responses have the following example of JSON-encoded body:

{
  "message": "OK",
  "code": 200
}

Bad Request response contains additional field describing specific errors:

{
  "message": "Bad Request",
  "code": 400,
  "errors": [
    "Project name is required."
  ]
}
Code HTTP Status Code Message
200 200 OK OK
400 400 Bad Request Bad Request
403 401 Unauthorized Unauthorized
403 403 Forbidden Forbidden
404 404 Not Found Not Found
405 405 Method Not Alowed Method Not Alowed
429 429 Too Many Requests Too Many Requests
500 500 Internal Server Error Internal Server Error
503 503 Service Unavailable Maintenance