Using the REST API

Beaconpush exposes a slim API through REST over HTTP. By design, this is a simple interface enabling you to send messages and controlling your users. Usually, it's only the server-side part of your web site talking to this API. But if authentication is turned off, browser-based JavaScript clients on your web page can also send messages.

To get started you'll need an HTTP client. It's usually included as a part of your favorite programming language's standard library. Ruby, Python and PHP all ships with ready-to-use HTTP clients. We are working on bringing native clients for popular platforms. If you've developed an open-source client or anything Beaconpush related, we'd love to put on our contributions page.

Server host is api.beaconpush.com. Response and request bodies are always JSON encoded. For examples of JSON structure for a specific API, head over to the test page.

Authentication

Beaconpush uses your account's secret key for authentication passed as a HTTP request header. Add an HTTP request header field to your HTTP request called "X-Beacon-Secret-Key" and set it's value to your secret key.

Try out the API right in your browser! Visit the "Test the API" page (logged in users only)

Using cURL for accessing the API

For those preferring more of a command-line approach to poke around in the API, cURL is a great tool. Below is an example of how to send a message using cURL.

curl -X POST --data-ascii "\"Hello World\"" -H "X-Beacon-Secret-Key: [secret key]" 
 http://api.beaconpush.com/1.0.0/[API key]/users/[username]

Sending a message to a channel

POST /1.0.0/[API key]/channels/[channel]

Sends a message to a channel. Request body MUST be valid JSON

Getting number of users online

GET /1.0.0/[API key]/users

Retrieves the number of users online

User-centered API resources

Below are the resources that are more user centered than the ones listed above. To make full use of these, you will need to give your users a unique username when embedding the client. Fair to say, this is right now more of a feature for power users.

Checking if a user is online

GET /1.0.0/[API key]/users/[username]

Response code is either 200 if user is online or 404 if user is offline. A corresponding JSON response body is also supplied

Forcing logout of a user

DELETE /1.0.0/[API key]/users/[username]

Forces the logout of a user. Result code is 204, hence no response body.

Listing users in a channel

GET /1.0.0/[API key]/channels/[channel]

Returns a JSON list of users in a channel

Sending a message to a user

POST /1.0.0/[API key]/users/[user]

Sends a message to a user. Request body MUST be valid JSON.