API
The API tab is another simple tab that shows you how you can query your API.
It shows an indicator showing that your API is online and active, information about API keys, your API's "schema", and an example of a valid API request.
Using this section, you can retrieve the API key for any user within your users table. By default, it will display the system user's ID and API key (a user which will have read only access to the API).
To get the API key for a different user, click into the "User" text box and start typing the user's username into it. An autocomplete box will appear letting you choose that user, and you'll be able to retrieve that user's API key.
When interacting with your API, you pass your API key via the Authorization header in your HTTP request. It gets passed in the format of "Basic <apikey>":
Basic dXNlcm5hbWU6cGFzc3dvcmQ=
A "schema" is a formal definition of data, showing what fields would get returned if you called the particular API you're looking at, as well as the type of data that will be getting returned back to you. Here are the various types that you can see:
Type | Description |
number | A numeric value |
string | A string of characters (text) |
airtable-id | An airtable record ID. Usually prefixed with "rec". |
owner-id | A record's owner ID. |
id | Internal SheetDream record ID |
date | A date value |
airtable-ref | An Airtable reference |
boolean | A true or false value |
Fields that are prefixed with an underscore (_) are internal fields used by SheetDream. You cannot directly modify any of these fields as they are controlled by SheetDream, and attempting to change any of them with a PUT/PATCH will just result in no change taking effect.
Each endpoint will have a list of REST API operations that it supports. In the example graphic above, this particular endpoint supports the GET operation, DELETE operation, and the POST operation.
Attempting to call a PUT or PATCH operation on this particular endpoint will result in a 404 error, as those particular operations are not supported by this endpoint.
The data that gets returned from your SheetDream API will be very consistent across all of your endpoints. Here is what the returned JSON will look like:
{
"status": "ok" | "failed",
"reason": "if status is failed, this will be populated",
"data": [{
...
}, ...]
}
If you are interacting with the API by any other means than the HTML / Handlebars.js route, it will be important to take note of the status and reason fields. A status field of "ok" means everything ran smoothly, and anything other than "ok" (generally "failed") will mean an error occurred and some sort of reason will be specified in the reason field.
SheetDream makes use of RESTful HTTP error codes. If your request fails and the returned result is a 50x error, in the 500-599 range, then that means it's an internal SheetDream error and probably requires developer attention.
If it's a 40x error, it means that either:
- You're not authenticated properly and received a 401 Not Found error in return
- You've attempted to hit an endpoint that doesn't exist and received a 404 Not Found error in return
- The particular document you attempted to retrieve in a GET request doesn't exist, and a 404 Not Found error was returned
- You've attempted to modify and/or access a record you do not have access to, in which case you will receive a 401 Unauthorized error in return
- You've attempted an operation that is considered forbidden at your access level, in which case you would receive a 403 Forbidden error in return
- You've reached the maximum number of API calls for your account plan, in which case you would receive a 429 Too Many Requests error in return
- SheetDream does not understand the JSON or some other aspect of your request, in which case you would most likely receive a 400 Bad Request in return
Last modified 1yr ago