API REST de base de datos de Firebase

Uso de la API

Puede usar cualquier URL de la base de datos en tiempo real de Firebase como punto final REST. Todo lo que necesita hacer es agregar .json al final de la URL y enviar una solicitud desde su cliente HTTPS favorito.

Se requiere HTTPS. Firebase solo responde al tráfico encriptado para que sus datos permanezcan seguros.

GET - Lectura de datos

Los datos de su base de datos en tiempo real se pueden leer emitiendo una solicitud HTTP GET a un punto final. El siguiente ejemplo demuestra cómo puede recuperar el nombre de un usuario que había almacenado previamente en Realtime Database.

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

Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK . La respuesta contiene los datos asociados con la ruta en la solicitud GET .

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

PUT - Escritura de datos

Puede escribir datos con una solicitud PUT .

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

Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK . La respuesta contiene los datos especificados en la solicitud PUT .

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

POST - Envío de datos

Para lograr el equivalente del método JavaScript push() (consulte Listas de datos ), puede emitir una solicitud POST .

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

Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK . La respuesta contiene el nombre secundario de los nuevos datos especificados en la solicitud POST .

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

PARCHE - Actualización de datos

Puede actualizar elementos secundarios específicos en una ubicación sin sobrescribir los datos existentes mediante una solicitud PATCH . Los hijos con nombre en los datos que se escriben con PATCH se sobrescriben, pero los hijos omitidos no se eliminan. Esto es equivalente a la función update() .

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

Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK . La respuesta contiene los datos especificados en la solicitud PATCH .

{ "last": "Jones" }

ELIMINAR - Eliminación de datos

Puede eliminar datos con una solicitud DELETE :

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

Una solicitud DELETE exitosa se indica mediante un código de estado HTTP 200 OK con una respuesta que contiene JSON null .

Anulación de método

Si realiza llamadas REST desde un navegador que no es compatible con los métodos anteriores, puede anular el método de solicitud realizando una solicitud POST y configurando su método mediante el encabezado de solicitud X-HTTP-Method-Override .

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

También puede usar el parámetro de consulta x-http-method-override .

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

Solicitudes condicionales

Las solicitudes condicionales, el equivalente REST de las operaciones de transacciones SDK, actualizan los datos de acuerdo con una determinada condición. Vea una descripción general del flujo de trabajo y obtenga más información sobre las solicitudes condicionales para REST en Guardar datos .

ETag de Firebase

Firebase ETag es el identificador único de los datos actuales en una ubicación específica. Si los datos cambian en esa ubicación, la ETag también cambia. El ETag de Firebase debe especificarse en el encabezado de la solicitud REST inicial (normalmente, un GET , pero puede ser cualquier cosa que no sea PATCH ).

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

si-coincidencia

La condición if-match especifica el valor de ETag para los datos que desea actualizar. Si utiliza la condición, Realtime Database solo completa las solicitudes en las que la ETag especificada en la solicitud de escritura coincide con la ETag de los datos existentes en la base de datos. Obtenga la ETag en una ubicación con una solicitud de ETag de Firebase. Si desea sobrescribir cualquier ubicación que sea nula, use null_etag .

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

Respuestas esperadas

La siguiente tabla proporciona una descripción general de las respuestas esperadas para cada tipo de solicitud, según la coincidencia de ETag.

tipo de solicitud 'X-Firebase-ETag: verdadero' coincidencias de ETag
if_match: <matching etag>
ETag no coincide
if_match: <no matching etag>
CONSEGUIR Estado/contenido de la respuesta 200: "<datos_en_ruta>" 400: "...no compatible..." 400: "...no compatible..."
Encabezados agregados ETag: <ETag_de_datos> N / A N / A
PONER Estado/contenido de la respuesta 200: "<poner_datos>" 200: "<poner_datos>" 412: "...Etag no coincide..."
Encabezados agregados ETag: <ETag_of_put_data> N / A ETag: <database_ETag>
CORREO Estado/contenido de la respuesta 200: "<datos_post>" 400: "...no compatible..." 400: "...no compatible..."
Encabezados agregados ETag: <ETag_of_post_data> N / A N / A
PARCHE Estado/contenido de la respuesta 400: "...no compatible..." 400: "...no compatible..." 400: "...no compatible..."
Encabezados agregados N / A N / A N / A
BORRAR Estado/contenido de la respuesta 200: nulo 200: "<datos_después_de_colocar>" 412: "...Etag no coincide..."
Encabezados agregados ETag: <ETag_of_null> N / A ETag: <database_ETag>

Parámetros de consulta

La API REST de la base de datos de Firebase acepta los siguientes valores y parámetros de consulta:

token_de_acceso

Compatible con todos los tipos de solicitudes. Autentica esta solicitud para permitir el acceso a los datos protegidos por las reglas de seguridad de la base de datos en tiempo real de Firebase. Consulte la documentación de autenticación REST para obtener más información.

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

poco profundo

Esta es una característica avanzada, diseñada para ayudarlo a trabajar con grandes conjuntos de datos sin necesidad de descargar todo. Establézcalo en true para limitar la profundidad de los datos devueltos en una ubicación. Si los datos en la ubicación son una primitiva JSON (cadena, número o booleano), simplemente se devolverá su valor. Si la instantánea de datos en la ubicación es un objeto JSON, los valores de cada clave se truncarán a true .

Argumentos Métodos de descanso Descripción
poco profundo CONSEGUIR Limite la profundidad de la respuesta.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Tenga en cuenta que shallow no se puede mezclar con ningún otro parámetro de consulta.

imprimir

Da formato a los datos devueltos en la respuesta del servidor.

Argumentos Métodos de descanso Descripción
bonito OBTENER, PONER, PUBLICAR, PARCHE, ELIMINAR Ver los datos en un formato legible por humanos.
silencioso OBTENER, PONER, PUBLICAR, PARCHE Se utiliza para suprimir la salida del servidor al escribir datos. La respuesta resultante estará vacía y se indicará con un código de estado HTTP 204 No Content .
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

llamar de vuelta

Compatible solo con GET . Para realizar llamadas REST desde un navegador web a través de dominios, puede usar JSONP para envolver la respuesta en una función de devolución de llamada de JavaScript. Agregue callback= para que la API REST envuelva los datos devueltos en la función de devolución de llamada que especifique.

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

formato

Si se configura para export , el servidor codificará las prioridades en la respuesta.

Argumentos Métodos de descanso Descripción
exportar CONSEGUIR Incluya información prioritaria en la respuesta.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

descargar

Compatible solo con GET . Si desea activar la descarga de un archivo de sus datos desde un navegador web, agregue download= . Esto hace que el servicio REST agregue los encabezados apropiados para que los navegadores sepan guardar los datos en un archivo.

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

se acabó el tiempo

Use esto para limitar el tiempo que tarda la lectura en el lado del servidor. Si una solicitud de lectura no finaliza dentro del tiempo asignado, finaliza con un error HTTP 400. Esto es particularmente útil cuando espera una pequeña transferencia de datos y no desea esperar demasiado para obtener un subárbol potencialmente enorme. El tiempo de lectura real puede variar según el tamaño de los datos y el almacenamiento en caché.

Especifique timeouts con el siguiente formato: 3ms , 3s o 3min , con un número y una unidad. Si no se especifica, se aplicará el timeout máximo de 15min . Si el timeout no es positivo o supera el máximo, la solicitud se rechazará con un error HTTP 400.

límite de tamaño de escritura

Para limitar el tamaño de una escritura, puede especificar el parámetro de consulta writeSizeLimit como tiny (objetivo = 1 s), small (objetivo = 10 s), medium (objetivo = 30 s), large (objetivo = 60 s). Realtime Database estima el tamaño de cada solicitud de escritura y anula las solicitudes que llevarán más tiempo que el objetivo.

Si especifica unlimited , se permiten escrituras excepcionalmente grandes (con una carga útil de hasta 256 MB), lo que podría bloquear las solicitudes posteriores mientras la base de datos procesa la operación actual. Las escrituras no se pueden cancelar una vez que llegan al servidor.

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

Verá el siguiente mensaje de error si la escritura es demasiado grande:

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

Además, puede establecer el defaultWriteSizeLimit para toda la instancia de la base de datos mediante Firebase CLI. Este límite se aplica a todas las solicitudes, incluidas las de los SDK. Las nuevas bases de datos se crean con defaultWriteSizeLimit establecido en large . No puede establecer defaultWriteSizeLimit en tiny mediante Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

ordenar por

Consulte la sección de la guía sobre datos ordenados para obtener más información.

limitToFirst, limitToLast, startAt, endAt, equalTo

Consulte la sección de la guía sobre filtrado de datos para obtener más información.

Transmisión desde la API REST

Los extremos REST de Firebase admiten el protocolo EventSource/Server-Sent Events . Para transmitir cambios a una sola ubicación en su base de datos en tiempo real, debe hacer algunas cosas:

  • Establezca el encabezado Aceptar del cliente en "text/event-stream"
  • Respete los redireccionamientos HTTP, en particular el código de estado HTTP 307
  • Si la ubicación requiere permiso para leer, debe incluir el parámetro auth

A cambio, el servidor enviará eventos con nombre a medida que cambie el estado de los datos en la URL solicitada. La estructura de estos mensajes se ajusta al protocolo EventSource .

event: event name
data: JSON encoded data payload

El servidor puede enviar los siguientes eventos:

poner

Los datos codificados en JSON son un objeto con dos claves: ruta y datos . La clave de ruta apunta a una ubicación relativa a la URL de solicitud. El cliente debe reemplazar todos los datos en esa ubicación en su caché con datos .

parche

Los datos codificados en JSON son un objeto con dos claves: ruta y datos . La clave de ruta apunta a una ubicación relativa a la URL de solicitud. Para cada clave en datos , el cliente debe reemplazar la clave correspondiente en su caché con los datos de esa clave en el mensaje.

mantener viva

Los datos de este evento son null . No se requiere ninguna acción.

Cancelar

Algunos errores inesperados pueden enviar un evento de "cancelar" y finalizar la conexión. La causa se describe en los datos proporcionados para este evento. Algunas posibles causas son las siguientes: 1. Las reglas de seguridad de la base de datos en tiempo real de Firebase ya no permiten una lectura en la ubicación solicitada. La descripción de `datos` para esta causa es "Permiso denegado". 2. Una escritura desencadenó un transmisor de eventos que envió un gran árbol JSON que supera nuestro límite, 512 MB. Los `datos` para esta causa son "La carga útil especificada es demasiado grande, solicite una ubicación con menos datos".

autenticación_revocada

Los datos de este evento son una cadena que indica que la credencial ha caducado. Este evento se envía cuando el parámetro auth proporcionado ya no es válido.

Aquí hay un ejemplo de un conjunto de eventos que el servidor puede enviar:

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

Prioridades

Se puede hacer referencia a la información de prioridad para una ubicación con un "niño virtual" llamado .priority . Puede leer prioridades con solicitudes GET y escribirlas con solicitudes PUT . Por ejemplo, la siguiente solicitud recupera la prioridad del nodo users/tom :

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

Para escribir prioridad y datos al mismo tiempo, puede agregar un elemento secundario .priority a la carga útil de JSON:

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

Para escribir prioridad y un valor primitivo (por ejemplo, una cadena) al mismo tiempo, puede agregar un elemento .priority y colocar el valor primitivo en un elemento .value :

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

Esto escribe "Tom" con una prioridad de 1.0 . Las prioridades se pueden incluir en cualquier profundidad en la carga útil de JSON.

Valores del servidor

Puede escribir valores de servidor en una ubicación utilizando un valor de marcador de posición que es un objeto con una única clave .sv . El valor de esa clave es el tipo de valor de servidor que desea configurar. Por ejemplo, la siguiente solicitud establece el valor del nodo en la marca de tiempo actual del servidor de Firebase:

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

También puede escribir prioridades usando los valores del servidor, usando la ruta "niño virtual" mencionada anteriormente.

Los valores de servidor admitidos incluyen:

Valor del servidor
marca de tiempo El tiempo desde la época de UNIX, en milisegundos.
incremento Proporcione un valor delta entero o de coma flotante, en la forma { ".sv": {"increment": <delta_value> }} , con el que incrementar atómicamente el valor actual de la base de datos. Si los datos aún no existen, la actualización establecerá los datos en el valor delta. Si el valor delta o los datos existentes son números de coma flotante, ambos valores se interpretarán como números de coma flotante y se aplicarán en el back-end como un valor doble. La aritmética doble y la representación de valores dobles siguen la semántica IEEE 754. Si hay un desbordamiento de enteros positivos/negativos, la suma se calcula como un doble.

Recuperar y actualizar las reglas de seguridad de Firebase Realtime Database

La API de REST también se puede usar para recuperar y actualizar las reglas de seguridad de la base de datos en tiempo real de Firebase para su proyecto de Firebase. Necesitará el secreto de su proyecto de Firebase, que puede encontrar en el panel Cuentas de servicio de la configuración de su proyecto de Firebase.

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

Autenticar solicitudes

De manera predeterminada, las solicitudes REST se ejecutan sin autenticación y solo tendrán éxito si las reglas de la base de datos en tiempo real permiten el acceso público de lectura o escritura a los datos. Para autenticar su solicitud, use los parámetros de consulta access_token= o auth= .

Obtenga más información sobre la autenticación a través de la API REST en Autenticar solicitudes REST .

Condiciones de error

La API REST de Firebase Database puede devolver los siguientes códigos de error.

Códigos de estado HTTP
400 Solicitud incorrecta

Una de las siguientes condiciones de error:

  • No se pueden analizar los datos PUT o POST .
  • Faltan datos PUT o POST .
  • La solicitud intenta PUT o POST datos que son demasiado grandes.
  • La llamada a la API REST contiene nombres secundarios no válidos como parte de la ruta.
  • La ruta de llamada de la API REST es demasiado larga.
  • La solicitud contiene un valor de servidor no reconocido.
  • El índice de la consulta no está definido en las reglas de seguridad de la base de datos en tiempo real de Firebase .
  • La solicitud no admite uno de los parámetros de consulta especificados.
  • La solicitud combina parámetros de consulta con una solicitud GET superficial.
401 no autorizado

Una de las siguientes condiciones de error:

404 No encontrado No se encontró la base de datos en tiempo real especificada.
500 Error interno del servidor El servidor devolvió un error. Consulte el mensaje de error para obtener más detalles.
503 Servicio no disponible La base de datos en tiempo real de Firebase especificada no está disponible temporalmente, lo que significa que no se intentó realizar la solicitud.
412 Precondición fallida El valor de ETag especificado de la solicitud en el encabezado if-match no coincide con el valor del servidor.