API Documentation

Getting Started

Welcome to the Cellmate API Documentation. Here, you'll find a request-response style guide for connecting to the API and interacting with your data housed in a Google Sheet.

This API follows the conventions of REST, with a twist. Each of your services is in itself a REST API. Here's a list of terms that might come up:

Google Terms Cellmate Terms
A Google Sheet A Service
Worksheets (tabs) Endpoints or Sheets
Rows Rows

Authorization

By default all GET requests to a service endpoint are public, and do not require authorization.

By default, all POST requests to a service endpoint require authorization.

After you create a token for your service, you'll need to send the token along in an Authorization header.

View Creating a Row for examples using the Authorization header.

Worksheets

List All Worksheets

GET /api/<service-id> 
Request
curl https://cellmateapp.com/api/<service-id>
$.getJSON("https://cellmateapp.com/api/<service-id>", function(results){
  results.forEach(function(result){
    console.log(result.title)
  })
})
Response
[
  {
    "title":"employees",
    "id":0,
    "url":"https://cellmateapp.com/api/<service-id>/employees"
   }
]

Retrieve One Worksheet

GET /api/<service-id>/<sheet-name> 
Request
curl https://cellmateapp.com/api/<service-id>/<sheet-name>
$.getJSON("https://cellmateapp.com/api/<service-id>/<sheet-name>", function(results){
  results.forEach(function(result){
    console.log(result.name)
  })
})
Response

[
  {
    "name": "Jesse Shawl",
    "position": "CEO",
    "email": "jesse@cellmateapp.com"
  },
  {
    "name": "Joe Schmoe",
    "position": "CFO",
    "email": "joes@example.com"
  },
  {
    "name": "Jane Schmane",
    "position": "COO",
    "email": "janes@example.com"
  }
]

Rows

List All Rows in a Worksheet

Getting a list of all the rows in a worksheet is the same thing as retrieving one worksheet. So, scroll up a little and follow the previous request/reponse example.

Retrieve One Row in a Worksheet

When retrieving values from a large worksheet, you can speed up the response time by only requesting what you need.

Note: The Row number matches the row number in the google sheet.

GET /api/<service-id>/<sheet-name>/
Request
curl https://cellmateapp.com/api/<service-id>/<sheet-name>/<row-number>
$.getJSON("https://cellmateapp.com/api/<service-id>/<sheet-name>/<row-number>", function(result){
  console.log(result.title)
})
Response
{
  "name": "Jesse Shawl",
  "position": "CEO",
  "email": "jesse@cellmateapp.com"
}

Create One Row

Note: keys without a corresponding column name will be ignored when POST'ed to cellmate.

POST /api/<service-id>/<sheet-name>
Request
curl -X POST \
  -H "Authorization: Token yourtokenhere" \
  -d "name=Janet Jameson&position=COO&email=janetj@example.com" \
  https://cellmateapp.com/api/<service-id>/<sheet-name>
$.ajax({
  type: "POST",
  url: "https://cellmateapp.com/api/<service-id>/<sheet-name>",
  data: {
    name: "Janet Jameson",
    position: "COO",
    email: "janetj@example.com"
  },
  headers: {
    "Authorization": "Token yourtokenhere"
  }
})
Response
{
  "name": "Janet Jameson",
  "position": "COO",
  "email": "janetj@example.com"
}

Update One Row

Note: keys without a corresponding column name will be ignored when PATCH'ed to cellmate.

PATCH /api/<service-id>/<sheet-name>/<row-number>
Request
curl -X PATCH \
  -H "Authorization: Token yourtokenhere" \
  -d "name=Janet Jameson&position=COO&email=janetj@example.com" \
  https://cellmateapp.com/api/<service-id>/<sheet-name>/<row-number>
$.ajax({
  type: "PATCH",
  url: "https://cellmateapp.com/api/<service-id>/<sheet-name>/<row-number>",
  data: {
    name: "Janet Jameson",
    position: "COO",
    email: "janetj@example.com"
  },
  headers: {
    "Authorization": "Token yourtokenhere"
  }
})
Response
{
  "name": "Janet Jameson",
  "position": "COO",
  "email": "janetj@example.com"
}

Delete One Row

Note: By default, rows are not removed from a spreadsheet. Sending a DELETE request via cellmate is the equivalent of selecting the row and pressing the backspace key.

If you are absolutely sure you want to delete a row (and affect the row numbers for others), you can add ?truncate=true to the URL.

DELETE /api/<service-id>/<sheet-name>/<row-number>
Request
curl -X DELETE \
  -H "Authorization: Token yourtokenhere" \
  https://cellmateapp.com/api/<service-id>/<sheet-name>/<row-number>
$.ajax({
  type: "DELETE",
  url: "https://cellmateapp.com/api/<service-id>/<sheet-name>/<row-number>",
  headers: {
    "Authorization": "Token yourtokenhere"
  }
})
Response
(intentionally blank)