Saving Data - REST API Development Guide - Helper Libraries - Developer Docs

REST API Development Guide

Saving Data

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.