GET - Reading Data

Data from yourRealtime Database can be read by issuing an HTTPGET request to an endpoint. The following example demonstrates how you might retrieve a user's name that you had previously stored inRealtime Database.

curl'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

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

PUT - Writing Data

You can write data with aPUT request.

curl-XPUT-d'{ "first": "Jack", "last": "Sparrow" }'\'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

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

POST - Pushing Data

To accomplish the equivalent of the JavaScriptpush() method (seeLists of Data), you can issue aPOST request.

curl-XPOST-d'{"user_id" : "jack", "text" : "Ahoy!"}'\'https://[PROJECT_ID].firebaseio.com/message_list.json'

A successful request is indicated by a200 OK HTTP status code. The response contains the child name of the new data specified in thePOST request.

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

PATCH - Updating Data

You can update specific children at a location without overwriting existing data using aPATCH request. Named children in the data being written withPATCH are overwritten, but omitted children are not deleted. This is equivalent to the JavaScriptupdate() function.

curl-XPATCH-d'{"last":"Jones"}'\'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

A successful request is indicated by a200 OK HTTP status code. The response contains the data specified in thePATCH request.

{ "last": "Jones" }

DELETE - Removing Data

You can delete data with aDELETE request:

curl-XDELETE\'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

A successfulDELETE request is indicated by a200 OK HTTP status code with a response containing JSONnull.

Method Override

If you make REST calls from a browser that does not support the preceding methods, you can override the request method by making aPOST request and setting your method by using theX-HTTP-Method-Override request header.

curl-XPOST-H"X-HTTP-Method-Override: DELETE"\'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

You can also use thex-http-method-override query parameter.

curl-XPOST\'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

Firebase ETag

The Firebase ETag is the unique identifier for the current data at a specified location. If the data changes at that location, the ETag changes, too. The Firebase ETag must be specified in the header for the initial REST request (typically aGET, but can be anything other thanPATCH).

curl-i'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json'-H'X-Firebase-ETag: true'

if-match

Theif-match condition specifies the ETag value for the data you want to update. If you use the condition,Realtime Database only completes requests where the ETag specified in the write request matches the ETag of the existing data in the database. Fetch the ETag at a location with a Firebase ETag request. If you want to overwrite any location that's null, usenull_etag.

curl-iXPUT-d'11''https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json'-H'if-match:[ETAG_VALUE]'

Expected responses

The following table provides an overview of the expected responses for each request type, based on the ETag match.

Query Parameters

The Firebase Database REST API accepts the following query parameters and values:

curl'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

curl'https://[PROJECT_ID].firebaseio/.json?shallow=true'

curl'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl-XPUT-d'{ "first": "Jack", "last": "Sparrow" }'\'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

<script>functiongotData(data){console.log(data);}</script><scriptsrc="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

curl'https://[PROJECT_ID].firebaseio.com/.json?format=export'

curl'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

Error:WRITE_TOO_BIG:Datatowriteexceedsthemaximumsizethatcanbemodifiedwithasinglerequest.

firebase database:settings:set defaultWriteSizeLimit large

firebase database:remove /large/path/to/delete

Streaming from the REST API

Firebase REST endpoints support theEventSource / Server-Sent Events protocol. To stream changes to a single location in yourRealtime Database, you 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 theauth parameter

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 theEventSource protocol.

event:eventnamedata:JSONencodeddatapayload

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:putdata:{"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:putdata:{"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:patchdata:{"path":"/c","data":{"foo":3,"baz":4}}

Priorities

Priority information for a location can be referenced with a "virtual child" named.priority. You can read priorities withGET requests and write them withPUT requests. For example, the following request retrieves the priority of theusers/tom node:

curl'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

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

curl-XPUT-d'{"name": {"first": "Tom"}, ".priority": 1.0}'\'https://[PROJECT_ID].firebaseio/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:

curl-XPUT-d'{".value": "Tom", ".priority": 1.0}'\'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

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

Server Values

You can write server values at a location using a placeholder value which is an object with a single.sv key. The value for that key is the type of server value you wish to set. For example, the following request sets the node's value to the Firebase server's current timestamp:

curl-XPUT-d'{".sv": "timestamp"}'\'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

You can also write priorities using server values, using the "virtual child" path noted above.

Supported server values include:

Retrieving and UpdatingFirebase Realtime Database Security Rules

The REST API can also be used to retrieve and update theFirebase Realtime Database Security Rules for your Firebase project. You'll need your Firebase project's secret, which you can find under theService Accounts panel of your Firebase project's setting.

curl'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'curl-XPUT-d'{ "rules": { ".read": true } }''https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

Authenticate requests

By default, REST requests are executed with no authentication and will only succeed if theRealtime Database Rules allow public read or write access to the data. To authenticate your request, use theaccess_token= orauth= query parameters.

Learn more about authentication through the REST API inAuthenticate REST Requests.