REST API documentation

This document describes how to work with Asyncnoti server. You’ll find it useful if none of our ready-made libraries suites you or if you’re writing your own library.



Communication with server

The API-server is hosted at http://asyncnoti.com/api/v1 and may be accessed via HTTP or HTTPS.

All requests must be signed by your application secret key (see Settings, the “Credentials” section) with HMAC SHA256 hex digest.

For GET requests parameters should be submitted in the query string.

For POST requests parameters should be submitted in the POST body as a JSON hash

Authenticating signature is generated from the following string:

   StringToSign = 
      HTTP_Verv + "\n" +
      Canonical_URI + "\n" +
      Canonical_Query_String + "\n"

Parameters description:

  • HTTP_Verb — request method in upper-case(for example, POST or GET)
  • Canonical_URI — Uri-encode’d way in RFC 3986. (for example, /api/v1/apps/1/events)
  • Canonical_Query_String — keys and values of the query, separated using the ampersand ( & ) character. The keys must be lower case and arranged in alphabetical order (The following example makes use of the Array parameter: alpha=zorg&delta[]=item1&delta[]=item2&gamma=Alisa)

The following query parameters must be included with all methods:

  • auth_key — your application key (used to authenticate the request)
  • auth_signature — authentication signature for the request — HMAC-SHA256(app_secret, StringToSign)
  • auth_timestamp — Unix time (POSIX time or Epoch time). The server will only accept requests where the timestamp is within 10 minutes of the current time.

Note, that the auth_key and auth_timestamp parameters take part in Canonical_Query_String.

Common HTTP status codes

  • 200 — Successful request.
  • 400 — Error: details may be contained in a JSON hash of response data (the “error” section)
  • 401 — Authentication error or wrong signature
  • 404 — The application has been deleted
  • 403 — Application temporarily disabled or over quota
  • 413 — Request Entity Too Large. The event data should not be larger than 10KB.



Trigger an event

POST /apps/{app_id}/events

Parameters:

  • name — Event name (required)
  • data — Event data in a valid JSON string (required)
  • data_hash — SHA256 hash/checksum of a data line (required)
  • channels — Array of one or more channel names - limited to 10 channels
  • channel — Channel name if publishing to a single channel. Can be used instead of the required ‘channels’ parameter.

Response:

  • In case of a success returns the following response {}
  • In case of an incorrect command returns one of the http-codes along with the object of type {code}{error: {message: ‘Error message description text’, code: ‘error code as http code status'}}



Get information for multiple channels

GET /apps/{app_id}/channels

Channels are created when at least one user subscribes to it.

Сhannels are destroyed when the last user unsubscribes.

Parameters:

  • prefix_filter — Filter the returned channels by a specific prefix(optional)
  • fields — fields array returned by channel (By default — user_count)

Available ‘fields’attributes:

  • user_count — Number of users subscribed to this channel

Response In case of success returns the following hash

{
      "channels": {
            "channel_name": {
                  "user_count": 1,
                  ...
            },
            ...
      }
}

Note! The responce is limited to 1000 items.



Get information for one channel

GET /apps/{app_id}/channels/{channel_name}

Parameters:

  • fields — fields array defining each channel (By default — user_count)

Available ‘fields’attributes repeat the ones mentioned in the method above.

ResponseIn case of success returns the following hash:

{
      "user_count": 1,
      ...
}


Get Application Stats

GET /apps/{app_id}/stats

Parameters:

  • fields — fields array returned by channel (By default — peak_connections, total_messages)

Available ‘fields’attributes:

  • peak_connections — maximum number of connections per 24 hrs
  • total_messages — amount of messages per 24 hrs

Response In case of success returns the stats information:

{
      "peak_connections": 4121,
      "total_messages": 453214
}