Introduction

The DonationAlerts public API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

HTTP API Requests

Requests and Responses

DonationAlerts public API endpoint for all HTTP methods is https://www.donationalerts.com/api/v1, unless specified otherwise.

All responses from our API are provided in JSON format, and in some cases, a 204 No Content response code with an empty response body may be returned.

Request example:

curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations \
    -H "Authorization: Bearer <token>"

Response example:

HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Sat, 1 Sep 2019 18:42:33 GMT
Content-Language: en_US
{
    "data": [
        {
            "id": 30530030,
            "name": "donation",
            "username": "Ivan",
            "message": "Hello!",
            "amount": 500,
            "currency": "RUB",
            "is_shown": 1,
            "created_at": "2019-09-29 09:00:00",
            "shown_at": null
        }
    ],
    "links": {
        "first": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "last": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://www.donationalerts.com/api/v1/alerts/donations",
        "per_page": 30,
        "to": 1,
        "total": 1
    }
}

Pagination

For the performance reasons DonationAlerts public API paginates the response output. This is because returning the entire data set might be feasible for some queries but prohibitive for others that return a very large amount of data.

API methods that support pagination will return meta and links parts in their response body.

meta
  • Parameter
    Description
  • current_page
    integer
    Current page index
    required
  • from
    integer
    First element index
    required
  • last_page
    integer
    Total number of pages
    required
  • path
    string
    The current path
    required
  • per_page
    integer
    Number of items per page
    required
  • to
    integer
    Last element index
    required
  • total
    integer
    Total number of items
    required
links
  • Parameter
    Description
  • first
    string
    Link to the first page
    required
  • last
    string
    Link to the last page
    required
  • prev
    string, null
    Link to the previous page. Or null if there no previous page
    required
  • next
    string, null
    Link to the next page. Or null if there no next page
    required

To specify a page, add the page parameter to the query.

The following example requests page 2:

curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations?page=2 \
    -H "Authorization: Bearer <token>"

Errors and Statuses

DonationAlerts uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with DonationAlerts' servers.

HTTP Statuses
  • Status
    Description
  • 200 OK
    Standard response for successful HTTP requests
  • 201 Created
    The request has been fulfilled, resulting in the creation of a new resource
  • 202 Accepted
    The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs
  • 204 No Content
    The server successfully processed the request and is not returning any content
  • 400 Bad Request
    The server cannot or will not process the request due to an apparent client error
  • 401 Unauthorized
    Authentication is required and has failed or has not yet been provided
  • 404 Not Found
    The requested resource could not be found but may be available in the future
  • 500 Internal Server Error
    A generic error message, given when an unexpected condition was encountered and no more specific message is suitable

Error example:

HTTP/1.1 401 Unauthorized
Server: nginx/1.13.5
Content-Type: application/json
{
    "message": "Unauthenticated."
}

Limitations

All API requests are subject to rate limits. We limit requests to our HTTP API methods for each application by 60 requests per minute, making it 1 request per second.

Centrifugo

We use Centrifugo to deliver real-time notifications when certain event occurs. It runs as standalone server and takes care of handling persistent connections from application users.

Centrifugo WebSocket connection endpoint:

wss://centrifugo.donationalerts.com/connection/websocket

Subscriptions to Centrifugo's private channels must be properly signed by API application. For the detailed information please read special chapter of Centrifugo documentation about private channel subscriptions.

Steps to Connect to the Centrifugo's WebSocket Server

  • Connecting to the Centrifugo WebSocket Server and obtaining Centrifugo's UUIDv4 Client ID
  • Subscribing to the Private Channels and Obtaining Connection Tokens
  • Connecting to the Private Channels

1. Connecting to the Centrifugo WebSocket Server and obtaining Centrifugo's UUIDv4 Client ID

In order to connect to the Centrifugo's WebSocket Server, first of all, you need to open connection with the Centrifugo WebSocket connection endpoint. Once connection is opened we need to send the message to the WebSocket server. This message must contain message ID and user Centrifugo connection token obtained earlier with the /user/oauth request. Such message must be JSON encoded and should look like this:

{
    "params": {
        "token": "<socket_connection_token>"
    },
    "id": 1
}
                        

In return you'll receive the message with generated Centrifugo's Client ID in form of UUIDv4 and Centrifugo version. This message looks like this:

{
    "id": 1,
    "result": {
        "client": "d558c046-c679-43e3-a62d-65989ab55f7c",
        "version": "2.2.1"
    }
}
                        

2. Subscribing to the Private Channels and Obtaining Connection Tokens

After getting the Centrifugo's UUIDv4 Client ID, you are ready to subscribe to the channels of our choice. Subscribing to the channels can be done with the following request:

POST https://www.donationalerts.com/api/v1/centrifuge/subscribe
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • channels
    string
    Array of private channel names to subscribe to
    required
  • client
    string
    Centrifugo UUIDv4 client ID obtained upon connection to the Centrifugo's WebSocket server
    required
curl \
    -X POST https://www.donationalerts.com/api/v1/centrifuge/subscribe \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{channels:["$alerts:donation_<user_id>"], client:"<uuidv4_client_id>"}'
  • Query String
    Description
  • channel
    string
    Private channel name
    required
  • token
    string
    Centrifugo connection token. This token can be used to connect to the private channel
    required
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "channels": [
        {
            "channel": "$alerts:donation_<user_id>",
            "token": "<connection_token>"
        }
    ]
}

Response contains array of the subscribed channels and tokens that can be now used to connect to the corresponding private channels.

3. Connecting to the Private Channels

Finally, in order to connect to the subscribed channels, you need to send another message via previously opened WebSocket connection. Each message must contain channel name and connection token, and should look like this:

{
    "params": {
        "channel": "$alerts:donation_<user_id>",
        "token": "<connection_token>"
    },
    "method": 1,
    "id": 2
}

After that, you'll receive confirmation message indicating successful channel connection:

{
   "result": {
        "type": 1,
        "channel": "$alerts:donation_3",
        "data": {
            "info": {
                "user": "1",
                "client": "d558c046-c679-43e3-a62d-65989ab55f7c"
            }
        }
    }
}

Now you are ready to receive real-time event notifications.

Authorization

We use the OAuth 2.0 authorization protocol to issue access to user data. If you are not familiar with the concept of OAuth 2.0, please read RFC 6749 first. All methods of DonationAlerts public API require authorization.

Grant Type: Authorization Code

The authorization code grant type used because it is optimized for server-side applications, where source code is not publicly exposed, and client secret confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent and receiving API authorization codes that are routed through the user-agent.

Access Token

Access tokens are the thing that applications use to make API requests on behalf of a user. The access token represents the authorization of a specific application to access specific parts of a user's data. Access tokens must be kept confidential in transit and in storage. The only parties that should ever see the access token are the application itself, the authorization server, and resource server. The application should ensure the storage of the access token is not accessible to other applications on the same device. The access token can only be used over an https connection, since passing it over a non-encrypted channel would make it trivial for third parties to intercept.

Scopes

Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.

The OAuth spec allows the authorization server or user to modify the scopes granted to the application compared to what is requested, although there are not many examples of services doing this in practice. OAuth does not define any particular values for scopes, since it is highly dependent on the service's internal architecture and needs.

DonationAlerts provides 3 scopes to third-party services:

DonationAlerts Scopes
  • Scope
    Description
  • oauth-user-show
    Obtain profile data
  • oauth-donation-subscribe
    Subscribe to new donation alerts
  • oauth-donation-index
    View donations

Authorization Steps

  • Application registration
  • Authorization request
  • Getting access token
  • Authorization code to access token exchange

1. Application Registration

The application developer must register the application here in order to get tokens. Once the application is registered, the authorization service will issue "client credentials" in the form of a client identifier and a client secret. The client_id is a publicly exposed string that is used by the service API to identify the application, and is also used to build authorization URLs that are presented to users. The client_secret is used to authenticate the identity of the application to the service API when the application requests to access a user’s account, and must be kept private between the application and the API.

2. Authorization Request

The user is given an authorization code link (or redirect) to the https://www.donationalerts.com/oauth/authorize with parameters client_id, redirect_uri, response_type and scope.

GET https://www.donationalerts.com/oauth/authorize
Request Parameters
  • Query String
    Description
  • client_id
    integer
    The client ID received from DonationAlerts
    required
  • redirect_uri
    string
    The URL in your where users will be sent after authorization
    required
  • response_type=code
    string
    Specifies that application is requesting an authorization code grant
    required
  • scope
    string
    A space-delimited list of scopes
    required

When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access to their account. Here is an example authorize application prompt.

3. Getting Authorization Code

If the user allows access to personal data, the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code. The authorization code will be available as the value of the code parameter.

4. Getting Access Token

The authorization code must be exchanged for an access token in https://www.donationalerts.com/oauth/token with grant_type, client_id, client_secret, redirect_uri and code parameters.

POST https://www.donationalerts.com/oauth/token
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • grant_type=authorization_code
    string
    The grant type
    required
  • client_id
    integer
    The application ID you received from DonationAlerts
    required
  • client_secret
    string
    The application secret you received from DonationAlerts
    required
  • redirect_uri
    string
    The URL where users will be sent after authorization
    required
  • code
    string
    The authorization code
    required
curl \
    -X POST https://www.donationalerts.com/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code&client_id=<client_id>
&client_secret=<client_secret>&redirect_uri=<redirect_uri>&code=<code>"
  • Query String
    Description
  • token_type
    string
    Token type
    required
  • expires_in
    integer
    Token expiration timestamp
    required
  • access_token
    string
    Access token
    required
  • refresh_token
    string
    Refresh token
    required
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "token_type": "Bearer",
    "access_token": "...msdisYBVnciOiJSUzI1NiIsImp0aSI6IjQxZDU0ZGQ2O...",
    "expires_in": 631151999,
    "refresh_token": "...173da4e0ff4d48c8cbde7a0071f770624a83259f0a11cd02ec1ce71fe924c4..."
}

Refreshing Access Tokens

The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired.

The service will generate and return a new access token if provided data is valid. The server may issue a new refresh token as well, but if the response does not contain a new refresh token the existing refresh token will still be valid.

POST https://www.donationalerts.com/oauth/token
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • grant_type=refresh_token
    string
    The grant type
    required
  • refresh_token
    string
    The refresh_token you received from DonationAlerts
    required
  • client_id
    integer
    The application ID you received from DonationAlerts
    required
  • client_secret
    string
    The application secret you received from DonationAlerts
    required
  • scope
    string
    A space-delimited list of scopes
    required
    curl \
    -X POST https://www.donationalerts.com/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>
&client_secret=<client_secret>&scope=<scope>"
  • Query String
    Description
  • token_type
    string
    Token type
    required
  • expires_in
    integer
    Token expiration timestamp
    required
  • access_token
    string
    Access token
    required
  • refresh_token
    string
    Refresh token
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "token_type": "Bearer",
    "access_token": "...msdisYBVnciOiJSUzI1NiIsImp0aSI6IjQxZDU0ZGQ2O...",
    "expires_in": 631151999,
    "refresh_token": "...173da4e0ff4d48c8cbde7a0071f770624a83259f0a11cd02ec1ce71fe924c4..."
}

API v1

Users

User Profile Information

Obtains user profile information. Requires user authorization with the oauth-user-show scope.

GET https://www.donationalerts.com/api/v1/user/oauth
Request Example Response Parameters Response Example
curl \
    -X GET https://www.donationalerts.com/api/v1/user/oauth \
    -H "Authorization: Bearer <token>"
  • Query String
    Description
  • id
    integer
    The unique and unchangeable user identifier
    required
  • code
    string
    The unique user name
    required
  • name
    string
    The unique displayed user name
    required
  • avatar
    string
    The URL to the personalized graphical illustration
    required
  • email
    string
    The email address
    required
  • socket_connection_token
    string
    Centrifugo connection token
    required
  • Please note that code and name may change at any time upon user rename
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "data": {
        "id": 3,
        "code": "tris_the_jam_master",
        "name": "Tris_the_Jam_Master",
        "avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/tris_the_jam_master-profile_image-c084755ce36ab72b-300x300.jpeg",
        "email": "support@donationalerts.com",
        "socket_connection_token": "yeJ0eXTYOiJKV1RiLCKhbGciOiJIU4.iJIUfeyJzdeyJzd.GciJIUfiOas_FCvQTYAA8usfsTYYFD"
    }
}

Donations

Donation Alerts List

Obtains array of objects of user donation alerts list. Requires user authorization with the oauth-donation-index scope.

GET https://www.donationalerts.com/api/v1/alerts/donations
Request Example Response Parameters Response Example
curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations \
    -H "Authorization: Bearer <token>"
  • Query String
    Description
  • id
    integer
    The unique donation alert identifier
    required
  • name
    string
    Type of the alert. Always donation in this case
    required
  • username
    string
    The name of the user who sent the donation and the alert
    required
  • message_type
    string
    The message type. Always text
    required
  • message
    string
    The message sent along with the donation and the alert
    required
  • amount
    number
    The donation amount
    required
  • currency
    string
    The currency code (ISO 4217 formatted)
    required
  • is_shown
    integer
    A flag indicating whether the alert was shown in the streamer's widget
    required
  • created_at
    string
    The donation date and time (YYYY-MM-DD HH.ii.ss formatted)
    required
  • shown_at
    string, null
    Date and time indicating when the alert was shown (YYYY-MM-DD HH.ii.ss formatted). Or null if the alert is not shown yet
    required
Please take message_type into consideration even though there are only text donation alerts available at the moment. We suggest to not utilize message if message_type contain unknown value for your application. Doing otherwise may lead to unexpected results
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "data": [
        {
            "id": 30530030,
            "name": "donation",
            "username": "Ivan",
            "message_type": "text",
            "message": "Hello!",
            "amount": 500,
            "currency": "RUB",
            "is_shown": 1,
            "created_at": "2019-09-29 09:00:00",
            "shown_at": null
        }
    ],
    "links": {
        "first": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "last": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://www.donationalerts.com/api/v1/alerts/donations",
        "per_page": 30,
        "to": 1,
        "total": 1
    }
}

Centrifugo Channels

DonationAlerts API offers the variety of Centrifugo channels for receiving real-time event notifications.

You can read more about Centrifugo in the Centrifugo section of this documentation.

New Donation Alerts

Subscribing to this channel allows to receive new user donation alerts. Requires user authorization with the oauth-donation-subscribe scope.

Centrifugo channel name — $alerts:donation_<user_id>

Choose your preferred platform:
By authorizing, you confirm that you have read carefully and agree to our Terms and our Privacy Policy.