Documentation

Introduction

This document is meant to be an overview of all of the capabilities of GraphQLSheet and how you can best leverage those capabilities. We will also help you understand exactly how GraphQLSheet works, the limitations, the permissions we are requesting to access your Google account and help you integrate the APIs you will create with your app. If you have any questions, please talk to us.

Getting Started

The API creation is super simple. We leverage Google APIs to log you in, ask for your permission to access Google Drive and then you can create the API for the Google Spreadsheet you want.

Overview

GraphQLSheet creates a GraphQL API from your Google Spreadsheet. Google offers a REST API that users can use but it's a lot more effort to setup yourself and of course, it's not GraphQL. GraphQL offers many advantages over REST such as a clean, self documented API (you can access GraphiQL for your GraphQLSheet APIs), multiple requests in one and you can request only that data fields you want.

Spreadsheets

Important: The spreadsheet must have string values (keys) or the first row and actual values (strings, number, booleans) on at least the second row to define the GraphQL schema.

A typical spreadsheet has columns with values with the first row having the column names. That's the assumption that GraphQLSheet is based on. We use the first row data as keys to create the GraphQLSheet schema and then analyze the column values to find patterns. If a column has numeric values, we define the GraphQL schema based on that information. We understand numbers, booleans and strings. To sum up, This is an example spreadsheet

Pricing

We currently offer 2 different pricing options. In both the Free and Plus packages, you can create as many GraphQLSheet APIs as you want. The main difference between the 2 packages is the number of requests that you can do. Please bare in mind that requests through GraphiQL are counted against your total available requests limit.

GraphQL API

If you ever used GraphQL, you know what it can do, and for sure you want to use it everywhere, and that's what GraphQLSheet is here to help with. We support Create Read Update and Delete operations, or Queries and Mutations as those are called in GraphQL.

Following is a complete example of a fetch request. You can use any language to do a simple POST request and use the API. Make sure to replace:

  • YOUR_API_TOKEN: with your token which you can find in your dashboard after you create your API.
  • YOUR_API_URL: with your API url, also found in the dashboard
  • YOUR_API_FIELDS: Values from the first row of your spreadhsheet
const queryData = async () => {
  const token = YOUR_API_TOKEN;
  const apiUrl = YOUR_API_URL;
  const response = await fetch(`${apiUrl}?token=${token}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(`
      {
        get (limit: 10) {
          YOUR_API_FIELDS
        }
      }
    `)
  });
  const responseJSON = await response.json();
  return responseJSON;
};

const data = queryData();
console.log(data);

Queries

Queries are used to retrieve data. We support a single but powerful query called "get".

Get

It can be used to get specific rows from the spreadsheet based on the params you use. Available params:

  • limit (Int): Max # of rows to read at once
  • offset (Int): Start reading from row #
  • orderBy (String): Column key to order by
  • query (String): Search for specific rows options

And it will return the matched rows of the spreadsheet.

For example

{
  get(limit: 10, offset: 2) {
    name
    age
  }
}

Mutations

Mutations is how we change data in the spreadsheet. We support "add", "update" and "remove".

Add

This mutation allows you to add new data in the spreadsheet. That data is added at the end of the spreadsheet. The params of this mutation depend on the structure of your spreadsheet and will be determined on the API creationg phase. All params are mandatory. This mutation returns the created row.

For example

mutation {
  add(name: "George", age: 12, height: 145, member: true) {
    name
    age
  }
}

Update

This mutation allows you to update specific rows in the spreadsheet. The params of this mutation depend on the structure of your spreadsheet and will be determined on the API creationg phase. Use the query to find the rows to update and the rest of the params for the values you want to update. This mutation returns an array with the updated rows.

For example

mutation {
  update(query: "name=George", age: 11, height: 142, member: false) {
    name
    age
  }
}

Remove

This mutation allows you to remove data from the spreadsheet. The params of this mutation depend on the structure of your spreadsheet and will be determined on the API creationg phase. Use the available params to find the rows to remove. This mutation returns an array with the deleted rows.

For example

mutation {
  remove(name: "George") {
    name
    age
  }
}

Authentication

Each API has a unique API token that you need to send with your request to access the data. That API secures that requests without it wont be able to read or write data to your spreadsheet.

Limitations

We currently support access only to the first sheet of your spreadsheet If you need access to a different sheet, the easiest solution right now is to create a new Google Spreasheet and move your data there, and create a GraphQLSheet API for it. Based on the user feedback we will consider adding the ability to access multiple sheets in the future.

HTTP Status Codes

We use stardard HTTP Status Codes to respond to your API requests

CodeDescription
200OK
400Bad Request
401Unauthorized
404Not Found
429Rate limit exceeded

Unauthorize GraphQLsheet

You can always revoke the GraphQLSheet's permission to access your Google Drive files in the Google Account Permissions page.

GraphQLSheet.com   ©  2019All rights reserved