Saving Data
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 '{ "username": "baileys", "date_of_birth": "June 9, 1978", "full_name": "Bailey Stringer"}' \
-H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec" \
https://api.flybase.io/apps/web/collections/users
When a JSON object is saved to Flybase, the object properties are automatically added to the collection you specified, in this case users
. Now if we navigate to our web
app in our dashboard, we’ll see the value “Bailey Stringer” in the users
collection.
The above example will result in the same data being saved to your Flybase app:
{
"users": {
"_id": "uniquedocumentid",
"username": "baileys",
"date_of_birth": "July 4, 2004",
"full_name": "Bailey Stringer"
}
}
Every record will have a unique _id
field, which we use later when we push updates.
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.Updating Existing Data
You can update existing data in one of two ways. The first is by passing data to a document matching the specified _id
. If no document matching the specified _id
already exists, it creates a new document. The data payload should contain a replacement document or update modifiers:
PUT /apps/{app}/collections/{collection}/{_id}
Content-Type: application/json
Body: <JSON data>
curl -X PUT -d '{ "x": "3" }' \
-H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec" \
https://api.flybase.io/apps/web/collections/users/1234
The other method to modify data is by performing a query which lets you modify multiple documents:
To update one or more documents in the specified collection, use a PUT
request with a replacement document or update modifiers in the body:
PUT /apps/{app}/collections/{collection}
Content-Type: application/json
Body: <JSON data>
Example setting “x” to 3 in the document with “_id” = 1234
curl -X PUT -d '{ "x": "3" }' \
-H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec" \
https://api.flybase.io/apps/web/collections/users?q={"_id":1234}
Server Values
Flybase lets you specify variables that are set on the server end. This is handy for dealing with cases such as users in multiple timezones and you want to store a timestamp locally to the Flybase servers.
Server Value | Definition |
---|---|
Flybase.ServerValue.TIMESTAMP | A placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) by the Flybase servers. |
Flybase.ServerValue.UTC | A placeholder value for auto-populating the current UTC date () by the Flybase servers. |
Flybase.ServerValue.UNIQUE | A placeholder value for auto-populating the field with a unique id. |
Flybase.ServerValue.UUID | A placeholder value for auto-populating the field with a unique UUID field. |
curl -X POST -d '{ "username": "baileys", "date_of_birth": "June 9, 1978", "full_name": "Bailey Stringer","registered_date": "Flybase.ServerValue.TIMESTAMP"}' \
-H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec" \
https://api.flybase.io/apps/web/collections/users
HTML Status Codes
The API commonly returns the following codes. For further reference, see W3C’s documentation.
HTTP Status Code | Description |
---|---|
200 – OK | Returned whenever a resource is listed, viewed, updated or deleted |
201 – Created | Returned whenever a resource is created (instead of code 200) |
400 – Bad Request | Returned whenever a request cannot be fulfilled because of an error with the input |
401 – Unauthorized | Returned either when no user credentials could be found or the credentials found are not authorized to perform the requested action |
403 – Forbidden | Returned whenever the server is refusing access to a resource, usually because the user does not have permissions to it |
404 – Not Found | Returned whenever the resource being requested does not exist |
405 – Method Not Allowed | Returned whenever the HTTP method (e.g. GET or POST) is not supported for the resource being requested |
In the next section on Reading Data, we’ll learn how to read this data from Flybase