While the easiest way to use Cloud Firestore is to use one of the native client libraries, there are some situations when it is useful to call the REST API directly.
The REST API can be helpful for the following use cases:
- Accessing Cloud Firestore from a resource-constrained environment, such as an internet of things (IoT) device, where running a complete client library is not possible.
- Automating database administration or retrieving detailed database metadata.
Authentication and authorization
Use Firebase ID tokens to authenticate requests from your application's users. For these requests, Cloud Firestore uses Cloud Firestore Security Rules to determine if a request is authorized.
Use a Google Identity OAuth 2.0 token and a service account to authenticate requests from your application, such as requests for database administration. For these requests, Cloud Firestore uses Cloud Identity and Access Management (IAM) to determine if a request is authorized.
Working with Firebase ID tokens
You can attain a Firebase ID token in two ways:
- Generate a Firebase ID token using the Firebase Authentication REST API.
- Retrieve a user's Firebase ID token from a Firebase Authentication SDK.
By retrieving a user's Firebase ID token, you can make requests on behalf of the user.
For requests authenticated with a Firebase ID token and for unauthenticated requests, Cloud Firestore uses your Cloud Firestore Security Rules to determine if a request is authorized.
Working with Google Identity OAuth 2.0 tokens
You can generate an access token by using a
service account with a
Google API Client Library
or by following the steps in
Using OAuth 2.0 for Server to Server Applications. You
can also generate a token with the
gcloud command-line tool and the
gcloud auth print-access-token.
This token must have the following scope to send requests to the Cloud Firestore REST API:
If you authenticate your requests with a service account and a Google Identity OAuth 2.0 token, Cloud Firestore assumes that your requests act on behalf of your application instead of an individual user. Cloud Firestore allows these requests to ignore your security rules. Instead, Cloud Firestore uses Cloud Identity and Access Management (IAM) to determine if a request is authorized.
You can control the access permissions of service accounts by assigning Cloud Firestore IAM roles.
Authenticating with an access token
After you obtain either a Firebase ID token or a Google Identity OAuth 2.0
token, pass it to the Cloud Firestore endpoints as an
header set to
Making REST calls
All REST API endpoints exist under the base URL
To create a path to a document with the ID
LA in the collection
under the project
YOUR_PROJECT_ID you would use the following structure.
To interact with this path, combine it with the base API URL.
The best way to begin experimenting with the REST API is to use the API Explorer, which automatically generates Google Identity OAuth 2.0 tokens and allows you to examine the API.
Perform actions on indexes such as creating new indexes, disabling an existing index, or listing all current indexes. Useful for automating data structure migrations or synchronizing indexes between projects.
Also enables retrieval of document metadata, such as the list of all fields and subcollections for a given document.