Firebase

REST API

API Usage

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.

HTTPS is required. Firebase only responds to encrypted traffic so that your data remains safe.

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 retrieved:

{ "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 overwritten, 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.

Method Override

If you are making REST calls from a browser that does not support the above methods, you can override the request method by making a POST and setting your method via a request header:

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
    'https://samplechat.firebaseio-demo.com/users/jack/name/last.json'

or a query parameter:

curl -X POST \
    'https://samplechat.firebaseio-demo.com/users/jack/name/last.json?x-http-method-override=DELETE'

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 and Firebase 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'
X-Firebase-Auth-Debug

If you set debug flag in the token then debug information can be found in the X-Firebase-Auth-Debug header of the response.

shallow

This is an advanced feature, designed to help you work with large datasets without needing to download everything. Set this to true to limit the depth of the data returned at a Firebase location. If the data at the location is a JSON primitive (string, number or boolean) its value will simply be returned. If the data snapshot at the location is a JSON object, the values for each key will be truncated to true.

Arguments REST Methods Description
shallow GET Limit the depth of the response.
curl 'https://samplechat.firebaseio-demo.com/.json?shallow=true'

print

Formats the data returned in the response from the server.

Arguments REST Methods Description
pretty GET, PUT, POST View the data in a human-readable format.
silent PUT, POST Used to suppress the output from the server when writing data. The response will be empty and indicated by a 204 OK HTTP status code
curl 'https://samplechat.firebaseio-demo.com/users/jack/name.json?print=pretty'
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) { console.log(data); }
</script>
<script src="https://samplechat.firebaseio-demo.com/users/fred/name/first.json?callback=gotData"></script>

format

If set to export, the server will encode priorities in the response.

Arguments REST Methods Description
export GET Include priority information in the response.
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'

orderBy

See the section in the guide on ordered data for more information.

limitToFirst, limitToLast, startAt, endAt, equalTo

See the section in the guide on querying data for more information.

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:

  • Set the client's Accept header to "text/event-stream"
  • Respect HTTP Redirects, in particular HTTP status code 307
  • If the location requires permission to read, you must include the auth parameter (see above in Query Parameters)

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:

put

The JSON-encoded data will be an object with two keys: path and data
The path points to a location relative to the request URL
The client should replace all of the data at that location in its cache with the data given in the message

patch

The JSON-encoded data will be an object with two keys: path and data
The path points to a location relative to the request URL
For each key in the data, the client should replace the corresponding key in its cache with the data for that key in the message

keep-alive

The data for this event is null, no action is required

cancel

The data for this event is null
This event will be sent if the security and Firebase rules cause a read at the requested location to no longer be allowed

auth_revoked

The data for this event is a string indicating that a the credential has expired
This event will be sent when the supplied auth parameter is no longer valid

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}}

Priorities

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

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.

Server Values

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:

ServerValue Description
timestamp The time since UNIX epoch, in milliseconds.

Retrieving and Updating Security and Firebase Rules

The REST API can also be used to retrieve and update the Security and Firebase Rules for your Firebase. You'll need your Firebase Secret, which you can find in Firebase Dashboard 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.

HTTP Status Code Description
404 Not Found A request made over HTTP instead of HTTPS
400 Bad Request Unable to parse PUT or POST data
400 Bad Request Missing PUT or POST data
400 Bad Request Attempting to PUT or POST data which is too large
417 Expectation Failed A REST API call that doesn't specify a namespace
400 Bad Request A REST API call that contains invalid child names as part of the path
403 Forbidden A request that violates your Security and Firebase Rules