PushTable Firestore API
The PushTable API provides an easy to use read-only API to access your Firestore data. We realize the official Firestore REST API can be difficult to use especially when integrating with static site builders. We have built a simple proxy API that gives you access to your data with much simpler authentication process and querying syntax.
Authentication
With the Google's official Firestore REST you have to setup a 2-legged OAuth2.0 process for server-to-server applications. However, PushTable provides a simple token based authentication that's much simpler and more appropriate for the use case of managing your own application content.
In the API tab of your project, you'll find your project API secret token. This token will give you access to the PushTable API. The PushTable API is built as a read-only API and you can simply pass the token in using the query parameter ?auth=<your_token>
// API_ENDPOINT
https://www.pushtable.com/api/cdn/<project_id>/firestore/<collection_id>?auth=<token>
For more details and sample code, please refer to the API tab in your project.
Queries
The PushTable API supports all the functionalities that is provided by the Firestore REST API runQuery method. You can always choose to implement any integration using the official REST API, PushTable just provides a simpler syntax that is more suited for the use case of a CMS. All the underlying principles of indexing and querying provided by Firestore still applies.
Supported Query Parameters
There are four basic query parameters, where orderBy limit and orderBy. where and orderBy are simply URI encoded JSON values. Please note that in simple cases where your JSON payload does not contain any reserved URI characters leaving your JSON un-encoded will work. However, to ensure all JSON values can be parsed correctly, encode all JSON parameters. In Javascript you can use the function encodeURIComponent()
For the purpose of this documentation, all the JSON parameters are left unencoded for clarity.
In PushTable, a query can be as simple as a single HTTP GET request:
GET: <API_ENDPOINT>?auth=<token>&where={"status":"published"}&limit=10&offset=10&orderBy={"name":"asc"}
Simple Filter Queries
The simplest type of query is just one that passes a plain javascript object value to match. In the following query, we are matching for any document that has SKU = "R2D21011"
GET: <API_ENDPOINT>?auth=<token>&where={"SKU":"R2D21011"}
GET: <API_ENDPOINT>?auth=<token>&where={"status":"published","tag":"news"}
Conditional Operators
In addition to query simple fields, you can use special operators to perform more advanced queries.
| Operator | Description | Example |
|---|---|---|
| $eq | == | {"price": {"$eq": 100}} |
| $gt | > | {"price": {"$gt": 100}} |
| $gte | >= | {"price": {"$gte": 100}} |
| $lt | < | {"price": {"$lt": 100}} |
| $lte | <= | {"price": {"$lte": 100}} |
The following query matches all documents where the price is less than 100.
GET: <API_ENDPOINT>?auth=<token>&where={"price":{"$lt":100}}
Compound Queries
To create compound queries you can simply add additional fields into your query object to match. However Firestore requires that certain compound queries to manually create custom indices. This is required when you are using a compound query with a range clause. Fortunately Firestore provides an easy to use interface for indexing and will provide a link in the error messages when you make a compound query without an index.
GET: <API_ENDPOINT>?auth=<token>&where={"price":{"$lt":100},"status":"AVAILABLE"}
Simple queries or compound queries that just act on a single field do not require a custom index to be created.
GET: <API_ENDPOINT>?auth=<token>&where={price:{"$lt":100,"$gte":10}}&orderBy={"price":"desc"}
GET: <API_ENDPOINT>?auth=<token>&where={"status":"AVAILABLE","tag":"cameras"}
Please note that the orderBy has to also act on the same field as well otherwise you will also need a custom index to be created.
Additionally, Firestore currently does not support using multiple inequality operators on different fields.
Sort Order
The orderBy query parameter is also an URI encoded JSON value.
| Operator | Description | Example |
|---|---|---|
| asc | Ascending order | {"price" : "asc"} |
| desc | Descending order | {"price" : "desc"} |
The following query matches all documents where the price is less than 100.
GET: <API_ENDPOINT>?auth=<token>&orderBy={"price":"asc"}
Pagination
Limit
The following request will return 25 documents per query.
GET: <API_ENDPOINT>?auth=<token>&limit=25
Offset
The following request will return documents starting at the 10th result of the query.
GET: <API_ENDPOINT>?auth=<token>&offset=10