Down to the details
Using the REST API
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.
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]"
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.