Subscription Mgmt - REST API

General

This secrion describing general information about the Subscription Management API.

Security

The use of the encryption is required. We are using protocols that are considered the best security practices.

Standards and conventions

This section represents used standards and conventions across all documents and API's.

Variables naming

All variables are named using the Snake case (or snake_case) naming convention. This means that words are separated by a single underscore _ character, no spaces are used, and letters are lowercase.

Time

For all input and output time values ISO 8601 standard is used.

Format specifier	Description
`yyyy`	The year as a four-digit number.
`MM`	The month, from 01 through 12.
`dd`	The day of the month, from 01 through 31.
`HH`	The hour, using a 24-hour clock from 00 to 23.
`mm`	The minute, from 00 through 59.
`ss`	The second, from 00 through 59.
`fff`	The milliseconds in a date and time value.
`fffffff`	The ten millionths of a second in a date and time value.

Input time values are parsed using the following formats as far as possible:

yyyy-MM-ddTHH:mm:ss.fffffff
yyyy-MM-ddTHH:mm:ss.fff
yyyy-MM-ddTHH:mm:ss
yyyy-MM-ddTHH:mm
yyyy-MM-ddTHH
yyyy-MM-dd
yyyyMMddTHHmmssfffffff
yyyyMMddTHHmmssfff
yyyyMMddTHHmmss
yyyyMMddTHHmm
yyyyMMddTHH
yyyyMMdd

Output time values are formatted using the following patterns:

yyyy-MM-ddTHH:mm:ss.fffffffZ
yyyy-MM-dd

Endpoints

Enviroment	Encryption	Value
Production	Yes	`https://www.coinapi.io/api/`

Authorization

To use resources that require authorized access, you will need to provide an API key to us when making HTTP requests.

There are 2 methods for passing the API key to us, you only need to use one:

Custom authorization header named X-CoinAPI-Key
Query string parameter named apikey

Custom authorization header

You can authorize by providing additional custom header named X-CoinAPI-Key and API key as its value.

Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY, then the authorization header you should send to us will look like:

X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY

Query string authorization parameter

You can authorize by providing an additional parameter named apikey with a value equal to your API key in the query string of your HTTP request.

Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY and that you want to request all exchange rates from BTC asset, then your query string should look like this:

GET /v1/exchangerate/BTC?apikey=73034021-THIS-IS-SAMPLE-KEY

HTTP Requests

Each HTTP request must contain the header Accept: application/json as all our responses are in JSON format.

We encourage you to use the HTTP request header Accept-Encoding: deflate, gzip for all requests. This will indicate to us that we can deliver compressed data to you which on your side should be decompressed transparently.

HTTP Success

Successful HTTP responses have the status code 200 and the body in a format according to documentation of the requested resource.

HTTP Errors

Error message is returned in JSON structured like this:

{
    "message": "Invalid API key"
}

All HTTP requests with response status codes different to 200 must be considered as failed and you should expect additional JSON inside the body of the response with the error message encapsulated inside it as shown in the example. We use the following error codes:

Error Code	Meaning
400	Bad Request -- There is something wrong with your request
401	Unauthorized -- Your API key is wrong
403	Forbidden -- Your API key doesnt't have enough privileges to access this resource
429	Too many requests -- You have exceeded your API key rate limits
550	No data -- You requested specific single item that we don't have at this moment.

Output data format

By default we are using JSON output data format for all of our endpoints, you can control format of data by using output_format variable in query string parameters.

URL Parameters

Parameter	Type	Description
output_format	string	Output data format (optional, default value is `json`, possible values are `json`, `xml` or `csv`)
csv_include_header	bool	Ignore header line in CSV output? (optional, default value is `true`, `true` to include CSV header line, `false` otherwise)
csv_include_quotes	bool	Encapsulate strings with quotes in CSV output? (optional, default value is `false`, `true` to encapsulate all strings with `"`, `false` to leave them unquoted)
csv_exclude_col	string	Comma delimited list of column names to ignore in CSV output (optional, by default all columns are included)
csv_set_delimiter	string	Character that will be used as column delimiter in CSV output (optional, default value is `;`)
csv_set_dec_mark	string	Character that will be used as decimal separator in CSV output (optional, default value is `.`)
csv_set_timeformat	string	Format for datetime type in CSV output or `unix` for unix timestamp (optional, default value is `yyyy-MM-ddTHH:mm:ss.fffffffZ`)
csv_set_newline	string	New line type (optional, default value is `unix`, possible values `win`, `mac`, `unix`)

Subscriptions

This section describes calls related to your API subscription.

REST usage GET

curl https://www.coinapi.io/api/subscriptions/usage/rest/history \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"

var client = new RestClient("https://www.coinapi.io/api/subscriptions/usage/rest/history");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);

<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/usage/rest/history');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

import requests
url = 'https://www.coinapi.io/api/subscriptions/usage/rest/history'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)

const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();

import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/usage/rest/history")
}

require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/usage/rest/history")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/usage/rest/history")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
  {
    "date": "2018-11-01",
    "requests": 691
  },
  {
    "date": "2018-10-31",
    "requests": 11779
  },
  {
    "date": "2018-10-30",
    "requests": 4275
  },
  {
    "date": "2018-10-29",
    "requests": 3495
  },
  {
    "date": "2018-10-27",
    "requests": 11
  },
  {
    "date": "2018-10-26",
    "requests": 56
  }
]

Get the historical daily number of requests used.

HTTP Request

GET /api/subscriptions/usage/rest/history
GET /api/subscriptions/usage/rest/history?date_start={date_start}
GET /api/subscriptions/usage/rest/history?date_end={date_end}
GET /api/subscriptions/usage/rest/history?date_start={date_start}&date_end={date_end}

URL Parameters

Parameter	Type	Description
date_start	datestring	Starting date (optional)
date_end	datestring	Ending date (optional)
limit	int	Amount of items to return (optional, mininum is 1, maximum is 100000, default value is 100, if the parameter is used then every 100 output items are counted as one request)

Output variables

Variable	Description
date	Date of the period
requests	Requests used in the period

Stream usage GET

curl https://www.coinapi.io/api/subscriptions/usage/stream/history \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"

var client = new RestClient("https://www.coinapi.io/api/subscriptions/usage/stream/history");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);

<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/usage/stream/history');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

import requests
url = 'https://www.coinapi.io/api/subscriptions/usage/stream/history'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)

const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();

import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/usage/stream/history")
}

require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/usage/stream/history")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/usage/stream/history")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
[
  {
    "date": "2018-11-01",
    "total_connections_days": 2.3030973986550922,
    "total_gigabytes_delivered": 40.2514768460354349,
    "total_messages_delivered": 45286100
  },
  {
    "date": "2018-10-31",
    "total_connections_days": 1.9242,
    "total_gigabytes_delivered": 46.42245,
    "total_messages_delivered": 224425
  }
]

Get the historical streaming usage log.

HTTP Request

GET /api/subscriptions/usage/stream/history
GET /api/subscriptions/usage/stream/history?date_start={date_start}
GET /api/subscriptions/usage/stream/history?date_end={date_end}
GET /api/subscriptions/usage/stream/history?date_start={date_start}&date_end={date_end}

URL Parameters

Parameter	Type	Description
date_start	datestring	Starting date (optional)
date_end	datestring	Ending date (optional)
limit	int	Amount of items to return (optional, mininum is 1, maximum is 100000, default value is 100, if the parameter is used then every 100 output items are counted as one request)

Output variables

Variable	Description
date	Date of the period
total_connections_days	Amount of connections days used in specific day
total_gigabytes_delivered	Amount of gigabytes of data delivered in specific day
total_messages_delivered	Number of messages delivered in specific day

Stream usage (detailed) GET

curl https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"

var client = new RestClient("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);

<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

import requests
url = 'https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)

const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();

import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history")
}

require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
  {
    "time_start": "2018-11-01T11:27:22.2855249Z",
    "time_end": "2018-11-01T11:31:02.4891607Z",
    "protocol_name": "WebSocket",
    "ip_client": "127.0.0.1",
    "bytes_send": 1845207,
    "bytes_recv": 297,
    "msgs_send": 1245,
    "msgs_recv": 1,
    "msgs_lost": 0
  },
  {
    "time_start": "2018-11-01T11:27:21.5511460Z",
    "time_end": "2018-11-01T11:31:01.7393780Z",
    "protocol_name": "WebSocket",
    "ip_client": "127.0.0.1",
    "bytes_send": 1842283,
    "bytes_recv": 297,
    "msgs_send": 1243,
    "msgs_recv": 1,
    "msgs_lost": 0
  },
  {
    "time_start": "2018-11-01T11:15:46.6302944Z",
    "time_end": "2018-11-01T11:26:41.5077182Z",
    "protocol_name": "WebSocket",
    "ip_client": "127.0.0.1",
    "bytes_send": 5488624,
    "bytes_recv": 297,
    "msgs_send": 3822,
    "msgs_recv": 1,
    "msgs_lost": 0
  }
]

Get the historical streaming detailed usage log.

HTTP Request

GET /api/subscriptions/usage/stream/detailed/history
GET /api/subscriptions/usage/stream/detailed/history?time_start={time_start}
GET /api/subscriptions/usage/stream/detailed/history?time_end={time_end}
GET /api/subscriptions/usage/stream/detailed/history?time_start={time_start}&time_end={time_end}

URL Parameters

Parameter	Type	Description
time_start	timestring	Log starting time in ISO 8601 (optional)
time_end	timestring	Log ending time in ISO 8601 (optional)
limit	int	Amount of items to return (optional, mininum is 1, maximum is 100000, default value is 100, if the parameter is used then every 100 output items are counted as one request)

Output variables

Variable	Description
time_start	Time on which data streaming was started
time_end	Time on which data streaming was ended
protocol_name	Protocol type used for data distribution (WebSocket/FIX)
ip_client	Client IP address from which connection was established
bytes_send	Bytes send on the connection by the CoinAPI
bytes_recv	Bytes received on the connection by the CoinAPI
msgs_send	Messages send on the connection by CoinAPI
msgs_recv	Messages received on the conncetion by CoinAPI
msgs_lost	Messages lost cased by the TCP client backpressure

Cancel GET

curl https://www.coinapi.io/api/subscriptions/cancel \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"

var client = new RestClient("https://www.coinapi.io/api/subscriptions/cancel");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);

<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/cancel');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

import requests
url = 'https://www.coinapi.io/api/subscriptions/cancel'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)

const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();

import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/cancel")
}

require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/cancel")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/cancel")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

Flag subscription for the cancelation at the end of the current billing period.

HTTP Request

GET /api/subscriptions/cancel?confirm=yes

Reactivate GET

curl https://www.coinapi.io/api/subscriptions/reactivate \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"

var client = new RestClient("https://www.coinapi.io/api/subscriptions/reactivate");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);

<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/reactivate');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

import requests
url = 'https://www.coinapi.io/api/subscriptions/reactivate'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)

const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();

import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/reactivate")
}

require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/reactivate")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/reactivate")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

Remove the subscription cancelation flag.

HTTP Request

GET /api/subscriptions/reactivate