REST API

You can use any Firebase URL as a REST endpoint. All you need to do is append ".json" to the end of the URL and send a request from your favorite HTTPS client. Note that HTTPS is required. Firebase only responds to encrypted traffic so that your data remains safe.

Helper Libraries

These libraries let you interact with Firebase via our REST API in your favorite language:


GET - Reading Data

Data from Firebase can be read by issuing an HTTP GET request to an endpoint:

curl https://SampleChat.firebaseIO-demo.com/users/jack/name.json

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

{"first":"Jack", "last": "Sparrow"}

PUT - Writing Data

Writing data with a PUT request:

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  https://SampleChat.firebaseIO-demo.com/users/jack/name.json

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

{"first":"Jack", "last": "Sparrow"}

POST - Pushing Data

To accomplish the equivalent of push( ) (see Lists of Data), you can issue a POST request:

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  https://SampleChat.firebaseIO-demo.com/message_list.json

A successful request will be indicated by a 200 OK HTTP status code. The response will contain the child name of the new data that was added:

{"name":"-INOQPH-aV_psbk3ZXEX"}

PATCH - Updating Data

You can update specific children at a location without overwriting existing data with a PATCH request. Named children in the data being written with PATCH will be written, but omitted children will not be deleted. This is equivalent to the update( ) function.

curl -X PATCH -d '{"last":"Jones"}' \
 https://SampleChat.firebaseIO-demo.com/users/jack/name/.json

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

{"last":"Jones"}

DELETE - Removing Data

Deleting data with a DELETE request:

curl -X DELETE \
  https://SampleChat.firebaseIO-demo.com/users/jack/name/last.json

A successful request will be indicated by a 204 OK HTTP status code with an empty response.

Legacy browser support

If you are making REST calls from a browser that does not support some of the above methods, Firebase supports the X-HTTP-Method-Override header.

Query Parameters

The Firebase REST API accepts these query parameters and values.

auth

Supported by all request types. Authenticates this request to allow access to data protected by security rules. The argument can either be your Firebase Secret or an authentication token. See Authentication for details.

curl \
https://SampleChat.firebaseIO-demo.com/users/jack/name.json?auth=CREDENTIAL

print

Supported by GET, PUT, and POST. If you’re debugging your application, you may find it useful to view the data in your Firebase in a human-readable format. Adding "print=pretty" to your request will accomplish this:

curl https://SampleChat.firebaseIO-demo.com/users/jack/name.json?print=pretty

Supported by PUT and POST. As an optimization you can add "print=silent" to suppress the output from the server when writing data to your Firebase. The response will be empty and indicated by a 204 OK HTTP status code

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  https://SampleChat.firebaseIO-demo.com/users/jack/name.json?print=silent

callback

Supported by GET only. To make REST calls from a web browser across domains you can use JSONP to wrap the response in a javascript callback function. Add "callback=" to have the REST API wrap the the returned data in the callback function you specify.

<script>
  function gotData(data) { alert(data); }
</script>
<script src="https://SampleChat.firebaseIO-demo.com/users/fred/name/first.json?callback=gotData"></script>

format

Supported by GET. Firebase stores priority data that does not normally exist in JSON documents (see Ordered Data). A normal GET request will not return this data. But if you are using the REST API to perform data backups, or are for any reason intending to pass this data back into Firebase at some point, you can preserve priority information by adding "format=export" to your request.

curl https://SampleChat.firebaseIO-demo.com/.json?format=export

download

Supported by GET. If you would like to trigger a file download of your data from a web browser, add "download=". This will cause our REST service to add the appropriate headers so that browsers know to save the data to a file.

curl https://SampleChat.firebaseIO-demo.com/.json?download=myfilename.txt

Streaming from the REST API

Firebase REST endpoints support the EventSource / Server-Sent Events protocol as well. To stream changes to a single location in your Firebase, you will need to do a few things:

In return, the server will send named events as the state of the data at the requested URL changes. The structure of these messages conforms to the EventSource protocol:

event: event name
data: JSON encoded data payload

The server may send the following events:

Here's an example set of events that the server may send:

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}


// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}


// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

Writing Priorities from the REST API

Priority information for a location can be referenced with a "virtual child" named ".priority". For example:

curl https://SampleChat.firebaseIO-demo.com/users/tom/.priority/.json

Priority can be read with GET and written with PUT.

To write priority and data at the same time, you can add a ".priority" child to the JSON payload bring written. For example:

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  https://SampleChat.firebaseIO-demo.com/users/tom/.json

To write priority and a primitive value (e.g. a string) at the same time, you can add a ".priority" child and put the primitive value in a ".value" child. For example:

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  https://SampleChat.firebaseIO-demo.com/users/tom/name/first.json

This writes "Tom" with a priority of 1.0. Priorities can be included at any depth in the JSON payload.

Writing Server Values from the REST API

Server values can be written at a location using a placeholder value, which is an object with a single ".sv" key and the value for that key is the type of server value you wish to set. For example, to set a timestamp:

curl -X PUT -d '{".sv": "timestamp"}' \
  https://SampleChat.firebaseIO-demo.com/users/tom/startedAtTime.json

Priorities may also be written using server values, using the "virtual child" path noted above.

Supported server values include:

Retrieving and Updating Security Rules

The REST API can also be used to retrieve and update the Security Rules for your Firebase. You'll need your Firebase Secret, which you can find in Forge (just enter your Firebase URL into a browser and log in) under the 'Auth' panel.

curl https://SampleChat.firebaseio-demo.com/.settings/rules.json?auth=FIREBASE_SECRET

curl -X PUT -d '{ "rules": { ".read": true } }' https://SampleChat.firebaseio-demo.com/.settings/rules.json?auth=FIREBASE_SECRET

Error Conditions

The Firebase REST API will return error codes under these circumstances.