Developer Docs

REST API Development Guide

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" \ 

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"

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:{"active": true}
	"c" example - return the count of documents with "active" of true:{"active": true}&c=true
	"f" example (include) - return all documents but include only the "firstName" and "lastName" fields:{"firstName": 1, "lastName": 1}
	"f" example (exclude) - return all documents but exclude the "notes" field:{"notes": 0}
	"fo" example - return a single document matching "active" field of true:{"active": true}&fo=true
	"s" example - return all documents sorted by "priority" ascending and "difficulty" descending:{"priority": 1, "difficulty": -1}
	"sk" and "l" example - sort by "name" ascending and return 10 documents after skipping 20{"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.

Return all documents where Query
status is "A" { "status": "A" } or
{ "status": { "$eq": "A" } }
status is NOT "A" { "status": { "$not": "A" } }
age > 25 { "age": { "$gt": 25 } }
age < 25 { "age": { "$lt": 25 } }
age > 25 AND age <= 50 { "age": { "$gt": 25, "$lte": 50 } }
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 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.