Skip to content

5 Minute Quickstart

Create an account

The first thing you need to do to get started with Flybase is sign up for a free account.

Once you sign up, create your first app and make a note of your API Key, and the name of your app. We’ll use this URL to store and sync data.

Base URL and headers

All URLs referenced in the documentation have the following base:

https://api.flybase.io/

The Flybase REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

In order to access any data from the REST API, you must pass a header called X-Flybase-API-KEY

curl -H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec"  https://api.flybase.io/

Calling the REST API without any actions in the URL will result in validating the API Key. You can also call the REST API with the following end point to validate the API key:

curl -H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec"  https://api.flybase.io/validate_key

An invalid API Key will result in not being able to do any other actions with the REST API. You can create new API Keys and add rules such as limiting access to apps or whitelisting access only to specified IP addresses or websites from your account.

Passing JSON Web Tokens

If you don’t want to pass your API key everytime then you can also pass a JSON web token.

This can be generated by passing the following query:

curl -X POST https://api.flybase.io/create-token/74c8062f-cd6f-4c07-8baf-b1h241496dec

This will return a JSON object with id_result as the key, copy the contents of id_result to use elsewhere.

Then you can pass the JSON token rather than your API key via one of two ways:

curl -H "Authorization: Bearer MYTOKEN  https://api.flybase.io/
curl https://api.flybase.io/?jwttoken=MYTOKEN

Either of these two methods work and provide a handy way to pass your api keys without actually passing your keys.

Write to your Flybase App

To create a new document in the specified collection:

POST /apps/{app}/collections/{collection}
Content-Type: application/json
Body: <JSON data>
curl -X POST -d '{ "first": "Jack", "last": "Sparrow" }' \
    -H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec" \
    https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION

If you POST a document that contains an _id field, the effect will be to overwrite any existing document with that _id. When your document already includes an _id value, think of POST like “save” or “upsert” (discussed below) rather than “create” or “insert”.

One consequence of this behavior: for a document with an _id specified, there is no straightforward way in the API to realize a pure “insert” — that is, an operation that refuses to modify a pre-existing document with that _id. POST will save over the old document; PUT will modify it. If this property is problematic for your application, consider using a field other than _id, with its own index to enforce uniqueness.

Read from your Flybase App

To get the documents in the specified collection. If no parameters are passed, it lists all of them. Otherwise, it lists the documents in the collection matching the specified parameters: :

GET /apps/{app}/collections/{collection}
curl -H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec"  https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION

A successful request will be indicated by a 200 OK HTTP status code. The response will contain the data being retrieved:

{ "_id": "uniquedocid-1", "first": "Jack", "last": "Sparrow", "active": 1}

All documents contain a _id field, you can use this for updating or deleting the document later. Any other fields depend on your structure

Optional parameters

Our optional parameters are based on MongoDB references, so you can build a query similar to how you would with MongoDB. This helps give you a lot of power and flexibility.

  • q=<query> – restrict results by the specified JSON query
  • c=true – return the result count for this query
  • f=<set of fields> – specify the set of fields to include or exclude in each document (1 – include; 0 – exclude)
  • fo=true – return a single document from the result set
  • s=<sort order> – specify the order in which to sort each specified field (1- ascending; -1 – descending)
  • sk=<num results to skip> – specify the number of results to skip in the result set; useful for paging
  • l=<limit> – specify the limit for the number of results (default is 1000)

Examples using these parameters:

"q" example - return all documents with "active" field of true:
https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION?q={"active": true}
"c" example - return the count of documents with "active" of true:
https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION?q={"active": true}&c=true
"f" example (include) - return all documents but include only the "firstName" and "lastName" fields:
https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION?f={"firstName": 1, "lastName": 1}
"f" example (exclude) - return all documents but exclude the "notes" field:
https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION?f={"notes": 0}
"fo" example - return a single document matching "active" field of true:
https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION?q={"active": true}&fo=true
"s" example - return all documents sorted by "priority" ascending and "difficulty" descending:
    https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION?s={"priority": 1, "difficulty": -1}
"sk" and "l" example - sort by "name" ascending and return 10 documents after skipping 20
https://api.flybase.io/apps/MY-APP/collections/MY-COLLECTION?s={"name":1}&sk=20&l=10