Reading Data
GETting a Document
To retrieve a single document, you just have to pass the _id
in the API request:
GET /apps/{app}/collections/{collection}/{_id}
curl -X GET -H "X-Flybase-API-Key: 74c8062f-cd6f-4c07-8baf-b1h241496dec" \
https://api.flybase.io/apps/web/collections/users/4e7315a65e4ce91f885b7dde
In the above example, the request will return the user who’s _id
matches 4e7315a65e4ce91f885b7dde
.Querying Documents
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/web/collections/users
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 queryc=true
– return the result count for this queryf=<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 sets=<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 pagingl=<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/web/collections/users?q={"active": true}
"c" example - return the count of documents with "active" of true: https://api.flybase.io/apps/web/collections/users?q={"active": true}&c=true
"f" example (include) - return all documents but include only the "firstName" and "lastName" fields: https://api.flybase.io/apps/web/collections/users?f={"firstName": 1, "lastName": 1}
"f" example (exclude) - return all documents but exclude the "notes" field: https://api.flybase.io/apps/web/collections/users?f={"notes": 0}
"fo" example - return a single document matching "active" field of true: https://api.flybase.io/apps/web/collections/users?q={"active": true}&fo=true
"s" example - return all documents sorted by "priority" ascending and "difficulty" descending: https://api.flybase.io/apps/web/collections/users?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/web/collections/users?s={"name":1}&sk=20&l=10
Query Language
If you’re familiar, with SQL, then our query language is slightly different, this table will show you a good representation of how our queries work.
status is "A":
{ "status": "A" } or { "status": { "$eq": "A" } }
status is NOT "A":
{ "status": { "$not": "A" } }
age > 25:
{ "age": { "$gt": 25 } }
status is "A" AND age > 25:
{ "$and": [ {"status": "A" }, {"age": { "$gt": 25 } } ] }
name contains "bc":
{ "name": { "$regex":"bc" } }
name is either ‘bob’ or ‘jake’:
{ "name" { "$in": ["bob", "jake"] } }
array contains "bob":
{ "name" { "$has": "bob" } }
array does not contain "bob":
{ "name" { "$nhas": "bob" } }
When calling fields, such as name
or age
, or when calling arguments such as $eq
, $not
, $gt
, $gte
, $lt
, $lte
, $regex
, $has
, $nhas
or $in
, always wrap them in quotes so that you would have "name"
, this is proper JSON, and is required for your queries to work. It also makes them easier to read!
As you can see, there is a lot you can do with the query system, and this helps greatly extend what you can do with your Flybase app
Now that we’ve covered retrieving data from Flybase, we’re ready for the next article on deleting data in Flybase.