{"_id":"56c2bc398073830d00e42e6f","__v":9,"category":{"_id":"56bc8e689afb8b0d00d62dd3","__v":6,"pages":["56bc8e699afb8b0d00d62dd5","56c2aadf46d27917009d0719","56c2bc123e1b8d2300fe4ca0","56c2bc1dde695a19009a4aa7","56c2bc2a46d27917009d0722","56c2bc398073830d00e42e6f"],"project":"56bc8e679afb8b0d00d62dcf","version":"56bc8e689afb8b0d00d62dd2","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-11T13:36:40.802Z","from_sync":false,"order":0,"slug":"documentation","title":"Getting Started"},"parentDoc":null,"version":{"_id":"56bc8e689afb8b0d00d62dd2","project":"56bc8e679afb8b0d00d62dcf","__v":18,"createdAt":"2016-02-11T13:36:40.146Z","releaseDate":"2016-02-11T13:36:40.146Z","categories":["56bc8e689afb8b0d00d62dd3","56c3c837bc41330d009f25ed","56c3c83e521f350d00d348eb","56c3c8452d97560d00e23cd8","56c3c85234df460d00c2beb8","56c4180d70187b17005f43b4","56c418162d97560d00e23cf6","56c4181cc4796b0d007ef039","56c4182370187b17005f43b5","56c418292e75e01700986052","56c4183328bd680d005e7ac6","56c4183bbb64720d00552b88","56c418414040602b0064cea0","56c4184754b6030d00ec29a1","56c4184c28bd680d005e7ac7","56c4185370187b17005f43b6","56c4185b6063071700500cfc","582a98b6f8c0a0190053d7a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"githubsync":"","project":"56bc8e679afb8b0d00d62dcf","user":"56b98db7bb36440d0001f492","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-16T06:05:45.202Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"### Overview\n\nThe Buddy REST API is the base entry point into the Buddy service. The REST API is intended for use with connected devices and for those who want to create highly-custom projects.\n\n### Prerequisites\n\nA REST client such as [Postman](http://www.getpostman.com/).\n\n### Getting the SDK\nThere are no local components for the REST SDK.\n\n### Installing the SDK\n\nNo installation is required.\n\n### Getting Started\n\nFor all of the calls below, the root URL to call will be `https://api.buddyplatform.com` however we will drop the root when we describe each call, e.g. `/devices` means `https://api.buddyplatform.com/devices`.\n\nMake sure that you specify the following headers for all calls to Buddy:\n\n* `Content-Type: application/json`\n* `Accept: application/json`\n\n#### Initialization\n\nNow we're ready to start building our application. The first thing we need to do is register with Buddy:\n\n POST /devices\n {\n appid: '[your app id]',\n appkey: '[your app key]',\n uniqueId: '[choose a random unique ID, like a UUID]'\n platform: 'REST Client'\n }\n\nThis authenticates your Buddy account and returns you an **access token**. Access tokens are what you will use to call most of the APIs on Buddy. Successful calls receive a response formatted as follows:\n\n {\n \"status\": 201,\n \"result\": {\n \"accessToken\": \"[access Token]\",\n \"accessTokenExpires\": \"/Date(1422514769546)/\"\n },\n \"request_id\": \"b625b290-cf69-405d-8091-b2c0f25a08c7\",\n \"success\": true\n }\n\nBehind the scenes you've traded your `appid` and `appkey` for an **application-level access token**. This access token lets you call APIs that _do not_ require user permissions, e.g. Create User or Record Metric Event.\n\n**Passing up a unique uniqueId is important to ensure that the device uses the same device registration across calls to Buddy for the associated app.**\n\nOnce you have an access token, you will need to include it as the Authorization header for your HTTP calls:\n\n`Authorization: Buddy [accessToken]` (don't include the brackets!)\n\n#### User Management\n\n##### User Creation\n\n POST /users\n {\n username: 'buddy',\n password: 'a.password',\n email: \"buddy:::at:::buddydemo.com\",\n firstName: 'Buddy',\n lastName: 'Demo'\n }\n\nThe response will look like:\n\n {\n \"status\": 200,\n \"result\": {\n \"celebMode\": false,\n \"locationFuzzing\": false,\n \"accessToken\": \"[accessToken]\",\n \"accessTokenExpires\": \"/Date(1422515312708)/\",\n \"firstName\": \"Buddy\",\n \"lastName\": \"Demo\",\n \"lastLogin\": \"/Date(1390979312700)/\",\n \"email\": \"[email protected]\",\n \"userName\": \"buddy\",\n \"id\": \"bv.gnkbbmsbqsJg\",\n \"created\": \"/Date(1390979312510)/\",\n \"lastModified\": \"/Date(1390979312700)/\"\n },\n \"request_id\": \"7b22e8af-f623-4618-8f18-5c8fe1e2aff8\",\n \"success\": true\n }\n\nTwo things to note here:\n\n1. The `accessToken` attribute works the same as the access token we received upon device registration but it is required for calling operations that require a user. _Don't forget to update your Authorization header with this new value._\n2. Creating the object returns all of its values and some extra information including an `id`. That `id` represents the user within your Buddy application and will be important for other operations.\n\n##### User Login\n\n POST /users\n {\n username: 'buddy',\n password: 'a.password'\n }\n\n##### User Logout\n\nUser logout does not have any extra parameters.\n\n POST /users/me/logout\n {\n }\n\n### More Sample Calls\n\n#### POST\n\nThis sample uses the access token retrieved from the user we just created:\n\n POST /checkins\n {\n location: '47,-121.8',\n comment: 'My first checkin',\n description: 'Pretty cool!'\n }\n\nAs you might expect, this returns us the information about the checkin:\n\n {\n \"status\": 201,\n \"result\": {\n \"comment\": \"My first checkin\",\n \"description\": \"Pretty cool!\",\n \"userID\": \"bv.gnkbbmsbqsJg\",\n \"id\": \"cb.hnkbbxtttsJg\",\n \"location\": {\n \"lat\": 47,\n \"lng\": -121.8\n },\n \"created\": \"/Date(1390979539770)/\",\n \"lastModified\": \"/Date(1390979539770)/\"\n },\n \"request_id\": \"fa22a06b-a8d4-476c-b163-30228bc6a791\",\n \"success\": true\n }\n\n#### GET\n\nNow we can retrieve a list of checkins using\n\n GET /checkins\n\nThe response comes in like so:\n\n {\n \"status\": 200,\n \"result\": {\n \"currentToken\": \"[paging token]\",\n \"pageResults\": [\n {\n \"comment\": \"My first checkin\",\n \"description\": \"Pretty cool!\",\n \"userID\": \"bv.gnkbbmsbqsJg\",\n \"id\": \"cb.hnkbbxtttsJg\",\n \"location\": {\n \"lat\": 47,\n \"lng\": -121.8\n },\n \"created\": \"/Date(1390979539770)/\",\n \"lastModified\": \"/Date(1390979539770)/\"\n }\n ]\n },\n \"request_id\": \"1db946ad-80fe-4cf6-b4ae-b14a498e5185\",\n \"success\": true\n }\n\n**Note:** The `pageResults` response object is used to return more than one result from a GET query.\n\nWe are able to return the checkin we created using the `id` from the POST response:\n\n GET /checkins/cb.hnkbbxtttsJg\n\n {\n \"status\": 200,\n \"result\": {\n \"comment\": \"My first checkin\",\n \"description\": \"Pretty cool!\",\n \"userID\": \"bv.gnkbbmsbqsJg\",\n \"id\": \"cb.hnkbbxtttsJg\",\n \"location\": {\n \"lat\": 47,\n \"lng\": -121.8\n },\n \"created\": \"/Date(1390979539770)/\",\n \"lastModified\": \"/Date(1390979539770)/\"\n },\n \"request_id\": \"279b65e5-196d-4534-a9e1-345e5d296e71\",\n \"success\": true\n }\n\n#### PUT/PATCH/DELETE\n\nEach remaining REST verb is available as detailed by the specific endpoint documentation.\n\n#### Tunneling\n\nSome clients are only able to send GET & POST verbs. For those clients, you can send the other HTTP verbs by creating [batch requests](doc:batch-requests).\n\n### Working With Files\n\nBuddy offers support for binary files; the REST interface functions similarly to the other endpoints.\n\nTo see details on file management visit the [HTTP File Uploads](doc:http-file-uploads) page.\n\n### Questions or need Help?\n\nThis should have given you the basics of how to work with the Buddy REST API. If you have further questions or are stuck, send an email to [[email protected]](mailto:[email protected]).","excerpt":"","slug":"rest-api","type":"basic","title":"REST API"}

Checkins

Batching

REST API

### Overview
The Buddy REST API is the base entry point into the Buddy service. The REST API is intended for use with connected devices and for those who want to create highly-custom projects.
### Prerequisites
A REST client such as [Postman](http://www.getpostman.com/).
### Getting the SDK
There are no local components for the REST SDK.
### Installing the SDK
No installation is required.
### Getting Started
For all of the calls below, the root URL to call will be `https://api.buddyplatform.com` however we will drop the root when we describe each call, e.g. `/devices` means `https://api.buddyplatform.com/devices`.
Make sure that you specify the following headers for all calls to Buddy:
* `Content-Type: application/json`
* `Accept: application/json`
#### Initialization
Now we're ready to start building our application. The first thing we need to do is register with Buddy:
POST /devices
{
appid: '[your app id]',
appkey: '[your app key]',
uniqueId: '[choose a random unique ID, like a UUID]'
platform: 'REST Client'
}
This authenticates your Buddy account and returns you an **access token**. Access tokens are what you will use to call most of the APIs on Buddy. Successful calls receive a response formatted as follows:
{
"status": 201,
"result": {
"accessToken": "[access Token]",
"accessTokenExpires": "/Date(1422514769546)/"
},
"request_id": "b625b290-cf69-405d-8091-b2c0f25a08c7",
"success": true
}
Behind the scenes you've traded your `appid` and `appkey` for an **application-level access token**. This access token lets you call APIs that _do not_ require user permissions, e.g. Create User or Record Metric Event.
**Passing up a unique uniqueId is important to ensure that the device uses the same device registration across calls to Buddy for the associated app.**
Once you have an access token, you will need to include it as the Authorization header for your HTTP calls:
`Authorization: Buddy [accessToken]` (don't include the brackets!)
#### User Management
##### User Creation
POST /users
{
username: 'buddy',
password: 'a.password',
email: "[email protected]",
firstName: 'Buddy',
lastName: 'Demo'
}
The response will look like:
{
"status": 200,
"result": {
"celebMode": false,
"locationFuzzing": false,
"accessToken": "[accessToken]",
"accessTokenExpires": "/Date(1422515312708)/",
"firstName": "Buddy",
"lastName": "Demo",
"lastLogin": "/Date(1390979312700)/",
"email": "[email protected]",
"userName": "buddy",
"id": "bv.gnkbbmsbqsJg",
"created": "/Date(1390979312510)/",
"lastModified": "/Date(1390979312700)/"
},
"request_id": "7b22e8af-f623-4618-8f18-5c8fe1e2aff8",
"success": true
}
Two things to note here:
1. The `accessToken` attribute works the same as the access token we received upon device registration but it is required for calling operations that require a user. _Don't forget to update your Authorization header with this new value._
2. Creating the object returns all of its values and some extra information including an `id`. That `id` represents the user within your Buddy application and will be important for other operations.
##### User Login
POST /users
{
username: 'buddy',
password: 'a.password'
}
##### User Logout
User logout does not have any extra parameters.
POST /users/me/logout
{
}
### More Sample Calls
#### POST
This sample uses the access token retrieved from the user we just created:
POST /checkins
{
location: '47,-121.8',
comment: 'My first checkin',
description: 'Pretty cool!'
}
As you might expect, this returns us the information about the checkin:
{
"status": 201,
"result": {
"comment": "My first checkin",
"description": "Pretty cool!",
"userID": "bv.gnkbbmsbqsJg",
"id": "cb.hnkbbxtttsJg",
"location": {
"lat": 47,
"lng": -121.8
},
"created": "/Date(1390979539770)/",
"lastModified": "/Date(1390979539770)/"
},
"request_id": "fa22a06b-a8d4-476c-b163-30228bc6a791",
"success": true
}
#### GET
Now we can retrieve a list of checkins using
GET /checkins
The response comes in like so:
{
"status": 200,
"result": {
"currentToken": "[paging token]",
"pageResults": [
{
"comment": "My first checkin",
"description": "Pretty cool!",
"userID": "bv.gnkbbmsbqsJg",
"id": "cb.hnkbbxtttsJg",
"location": {
"lat": 47,
"lng": -121.8
},
"created": "/Date(1390979539770)/",
"lastModified": "/Date(1390979539770)/"
}
]
},
"request_id": "1db946ad-80fe-4cf6-b4ae-b14a498e5185",
"success": true
}
**Note:** The `pageResults` response object is used to return more than one result from a GET query.
We are able to return the checkin we created using the `id` from the POST response:
GET /checkins/cb.hnkbbxtttsJg
{
"status": 200,
"result": {
"comment": "My first checkin",
"description": "Pretty cool!",
"userID": "bv.gnkbbmsbqsJg",
"id": "cb.hnkbbxtttsJg",
"location": {
"lat": 47,
"lng": -121.8
},
"created": "/Date(1390979539770)/",
"lastModified": "/Date(1390979539770)/"
},
"request_id": "279b65e5-196d-4534-a9e1-345e5d296e71",
"success": true
}
#### PUT/PATCH/DELETE
Each remaining REST verb is available as detailed by the specific endpoint documentation.
#### Tunneling
Some clients are only able to send GET & POST verbs. For those clients, you can send the other HTTP verbs by creating [batch requests](doc:batch-requests).
### Working With Files
Buddy offers support for binary files; the REST interface functions similarly to the other endpoints.
To see details on file management visit the [HTTP File Uploads](doc:http-file-uploads) page.
### Questions or need Help?
This should have given you the basics of how to work with the Buddy REST API. If you have further questions or are stuck, send an email to [[email protected]](mailto:[email protected]).