{"_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"}
### 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]).