TheFirebase Hosting REST API enablesprogrammatic and customizable deployments to your Firebase-hosted sites.Use this REST API to deploy new or updatedHosting content andconfiguration.

As an alternative to using theFirebase CLI fordeployments, you can use theFirebase Hosting REST API to programmaticallycreate a newversion ofassets for your site, upload files to the version, then deploy the version toyour site.

For example, with theFirebase Hosting REST API, you can:

• Schedule deploys. By using the REST API in conjunction with a cron job,you can change Firebase-hosted content on a regular schedule (for example, todeploy a special holiday or event-related version of your content).

• Integrate with developer tools. You can create an option in your tool todeploy your web app projects toFirebase Hosting using just one click (forexample, clicking a deploy button within an IDE).

• Automate deploys when static content is generated. When a processgenerates static content programmatically (for example, user-generated contentsuch as a wiki or a news article), you can deploy the generated content asstatic files rather than serving them dynamically. This saves you expensivecompute power and serves your files in a more scalable way.

This guide first describes how to enable, authenticate, and authorize the API.Then this guide walks through an example to create aFirebase Hostingversion, to upload required files to the version, then finally to deploy theversion.

You can also learn more about this REST API in thefullHosting REST API reference documentation.

Before you begin: Enable the REST API

You must enable theFirebase Hosting REST API in the Google APIs console:

1. Open theFirebase Hosting API page in the Google APIs console.

2. When prompted, select your Firebase project.

   Note: Every Firebase project has a corresponding project in the Google APIsconsole.

3. ClickEnable on theFirebase Hosting API page.

Step 1: Get an access token to authenticate and authorize API requests

Firebase projects support Googleservice accounts,which you can use to call Firebaseserver APIs from your app server or trusted environment. If you're developingcode locally or deploying your application on-premises,you can use credentials obtainedvia this service account to authorize server requests.

To authenticate a service account and authorize itto access Firebase services, you must generate a private key file in JSONformat.

To generate a private key file for your service account:

1. In theFirebase console, openSettings >Service Accounts.

2. ClickGenerate New Private Key, then confirm by clickingGenerate Key.

3. Securely store the JSON file containing the key.

Use your Firebase credentials together withtheGoogle Auth Libraryfor your preferred language to retrieve a short-lived OAuth 2.0 access token:

const{google}=require('googleapis');functiongetAccessToken(){returnnewPromise(function(resolve,reject){varkey=require('./service-account.json');varjwtClient=newgoogle.auth.JWT(key.client_email,null,key.private_key,SCOPES,null);jwtClient.authorize(function(err,tokens){if(err){reject(err);return;}resolve(tokens.access_token);});});}

def_get_access_token():"""Retrieve a valid access token that can be used to authorize requests.  :return: Access token.  """credentials=ServiceAccountCredentials.from_json_keyfile_name('service-account.json',SCOPES)access_token_info=credentials.get_access_token()returnaccess_token_info.access_token

privatestaticStringgetAccessToken()throwsIOException{GoogleCredentialgoogleCredential=GoogleCredential.fromStream(newFileInputStream("service-account.json")).createScoped(Arrays.asList(SCOPES));googleCredential.refreshToken();returngoogleCredential.getAccessToken();}

After your access token expires, the token refresh method is calledautomatically to retrieve an updated access token.

Step 2: Ensure that your project has a defaultHosting site

Before your first deployment toFirebase Hosting, your Firebase project musthave a defaultHostingSITE.

1. Check if your project already has a defaultHosting site by calling thesites.listendpoint.

   For example:

   cURL command

   curl -H "Content-Type: application/json" \       -H "Authorization: BearerACCESS_TOKEN" \https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites

   Raw HTTPS request

   Host:firebasehosting.googleapis.comPOST/v1beta1/projects/PROJECT_ID/sites HTTP/1.1Authorization:BearerACCESS_TOKENContent-Type:application/json

   • If one of the sites has"type": "DEFAULT_SITE", then your projectalready has a defaultHosting site. Skip the remainder of this step,and move onto the next step:Create a new version for your site.

   • If you get an empty array, then you don't have a defaultHostingsite. Complete the remainder of this step.

2. Decide on theSITE_ID for your defaultHosting site. Keep thefollowing in mind when deciding thisSITE_ID:

   • ThisSITE_ID is used to create your default Firebase subdomains:
     SITE_ID.web.app andSITE_ID.firebaseapp.com.

   • ASITE_ID has the following requirements:

     • Must be a valid hostname label, meaning it cannot contain.,_, etc.
     • Must be 30 characters or fewer
     • Must be globally unique within Firebase

   Note that we often recommend using your project ID as theSITE_ID for yourdefaultHosting site. Learn how to find this ID inUnderstand Firebase projects.

3. Create your defaultHosting site by calling thesites.createendpoint using your desiredSITE_ID as thesiteId parameter.

   For example:

   cURL command

   curl -H "Content-Type: application/json" \       -H "Authorization: BearerACCESS_TOKEN" \https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites?siteId=SITE_ID

   Raw HTTPS request

   Host:firebasehosting.googleapis.comPOST/v1beta1/projects/PROJECT_ID/sites?siteId=SITE_IDAuthorization:BearerACCESS_TOKENContent-Type:application/json

   This API call tosites.create returns the following JSON:

   {"name":"projects/PROJECT_ID/sites/SITE_ID","defaultUrl":"https://SITE_ID.web.app","type":"DEFAULT_SITE"}

   If you decide to use your project ID as theSITE_ID, note the following:

   In rare cases, your project ID has already been used by another project to create aHosting site. In these cases, the call tosites.create returns a 400 error message that says the providedSITE_ID isreserved by another project. To resolve this error, try callingsites.create again either using the suggested string in the error message or another string until the call succeeds.

Step 3: Create a new version for your site

Your first API call is to create a newVersion for your site.Later in this guide, you’ll upload files to this version, then deploy it to yoursite.

1. Determine theSITE_ID for the site to which you want to deploy.

   Note: For your defaultHosting site, theSITE_ID is your Firebase project ID (which is used to create your Firebase subdomainsSITE_ID.web.app andSITE_ID.firebaseapp.com).
   If you’ve createdmultiple sites in your Firebase project, make sure that you’re using theSITE_ID of the site to which you’d like to deploy.

2. Call theversions.createendpoint using yourSITE_ID in the call.

   (Optional) You can also pass aFirebase Hosting configuration objectin the call, including setting a header that caches all files for a specifiedlength of time.

   For example:

   cURL command

   curl -H "Content-Type: application/json" \       -H "Authorization: BearerACCESS_TOKEN" \       -d '{             "config": {               "headers": [{                 "glob": "**",                 "headers": {                   "Cache-Control": "max-age=1800"                 }               }]             }           }' \https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions

   Raw HTTPS request

   Host:firebasehosting.googleapis.comPOST/v1beta1/sites/SITE_ID/versions HTTP/1.1Authorization:BearerACCESS_TOKENContent-Type:application/jsonContent-Length:134{"config":{"headers":[{"glob":"**","headers":{"Cache-Control":"max-age=1800"}}]}}

This API call toversions.create returns the following JSON:

{  "name": "sites/SITE_ID/versions/VERSION_ID",  "status": "CREATED",  "config": {    "headers": [{      "glob": "**",      "headers": {        "Cache-Control": "max-age=1800"      }    }]  }}

This response contains a unique identifier for the new version, in the format:sites/SITE_ID/versions/VERSION_ID. You’llneed this unique identifier throughout this guide to reference this specificversion.

Step 4: Specify the list of files you want to deploy

Now that you have your new version identifier, you need to tellFirebase Hosting which files you want to eventually deploy in this newversion.

Note thatHosting has a maximum size limit of 2 GB forindividual files.

This API requires that you identify files by a SHA256 hash. So, before you canmake the API call, you’ll first need to calculate a hash for each static file byGzipping the files then taking the SHA256 hash of each newly compressed file.

1. Gzip the files:

   gzip file1 && gzip file2 && gzip file3

   You now have three compressed filesfile1.gz,file2.gz, andfile3.gz.

2. Get the SHA256 hash of each compressed file:

   cat file1.gz | openssl dgst -sha25666d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

   cat file2.gz | openssl dgst -sha256490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

   cat file3.gz | openssl dgst -sha25659cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

   You now have the three SHA256 hashes of the three compressed files.

3. Send these three hashes in an API request to theversions.populateFilesendpoint. List each hash by the desired path for the uploaded file (in thisexample,/file1,/file2, and/file3).

   For example:

   cURL command

   $ curl -H "Content-Type: application/json" \         -H "Authorization: BearerACCESS_TOKEN" \         -d '{               "files": {                 "/file1": "66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4",                 "/file2": "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083",                 "/file3": "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"               }             }' \https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFiles

   Raw HTTPS Request

   Host:firebasehosting.googleapis.comPOST/v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFiles HTTP/1.1Authorization:BearerACCESS_TOKENContent-Type:application/jsonContent-Length:181{"files":{"/file1":"66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4","/file2":"490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083","/file3":"59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"}}

This API call toversions.populateFiles returns the following JSON:

{"uploadRequiredHashes":["490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083","59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"],"uploadUrl":"https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files"}

This response includes:

• Thehash of each file that needs to be uploaded. For instance, in thisexamplefile1 had already been uploaded in a previous version, so its hashis not included in theuploadRequiredHashes list.

  Note: Some files in your new version don’t need to be uploaded, for example,if the file was already in a previous version and is unmodified for the newversion.

• TheuploadUrl which is specific to the new version.

In the next step to upload the two new files, you’ll need the hashes and theuploadURL from theversions.populateFiles response.

Step 5: Upload required files

You need to individually upload each required file (those files which are listedinuploadRequiredHashes from theversions.populateFiles response in theprevious step). For these file uploads, you’ll need the file hashes and theuploadUrl from the previous step.

1. Append aforward slash and thehash of the file to theuploadUrl tocreate a file-specific URL in the format:https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH.

2. Upload all the required files one-by-one (in this example, onlyfile2.gzandfile3.gz) to the file-specific URL using a series of requests.

   For example, to upload the compressedfile2.gz:

   cURL command

   curl -H "Authorization: BearerACCESS_TOKEN" \       -H "Content-Type: application/octet-stream" \       --data-binary @./file2.gz \https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH

   Raw HTTPS Request

   Host:upload-firebasehosting.googleapis.comPOST/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASHHTTP/1.1Authorization:BearerACCESS_TOKENContent-Type:application/octet-streamContent-Length:500content-of-file2.gz

Successful uploads return a200 OK HTTPS response.

Step 6: Update the status of the version to FINALIZED

After you’ve uploaded all the files which are listed in theversions.populateFiles response, you can update the status of your version toFINALIZED.

Call theversions.patchendpoint with thestatus field in your API request set toFINALIZED.

For example:

curl -H "Content-Type: application/json" \       -H "Authorization: BearerACCESS_TOKEN" \       -X PATCH \       -d '{"status": "FINALIZED"}' \https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status

Host:firebasehosting.googleapis.comPATCH/v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status HTTP/1.1Authorization:BearerACCESS_TOKENContent-Type:application/jsonContent-Length:23{"status":"FINALIZED"}

This API call toversions.patch returns the following JSON. Check thatstatus has been updated toFINALIZED.

{"name":"sites/SITE_ID/versions/VERSION_ID","status":"FINALIZED","config":{"headers":[{      "glob": "**",      "headers": {"Cache-Control": "max-age=1800"}    }]},"createTime":"2018-12-02T13:41:56.905743Z","createUser":{"email":"SERVICE_ACCOUNT_EMAIL@SITE_ID.iam.gserviceaccount.com"},"finalizeTime":"2018-12-02T14:56:13.047423Z","finalizeUser":{"email":"USER_EMAIL@DOMAIN.tld"},"fileCount":"5","versionBytes":"114951"}

Step 7: Release the version for deployment

Now that you have a finalized version, release it for deployment. For this step,you need to create aRelease of your versionthat contains the hosting configuration and all the content files for your newversion.

Call thereleases.createendpoint to create your release.

For example:

curl -H "Authorization: BearerACCESS_TOKEN" \       -X POSThttps://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID

Host:firebasehosting.googleapis.comPOST/v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID HTTP/1.1Authorization:BearerACCESS_TOKEN

This API call toreleases.create returns the following JSON:

{"name":"sites/SITE_ID/releases/RELEASE_ID","version":{"name":"sites/SITE_ID/versions/VERSION_ID","status":"FINALIZED","config":{"headers":[{"glob":"**","headers":{"Cache-Control":"max-age=1800"}}]}},"type":"DEPLOY","releaseTime":"2018-12-02T15:14:37Z"}

The hosting configuration and all the files for the new version should now bedeployed to your site, and you can access your files using the URLs:

• https://SITE_ID.web.app/file1
• https://SITE_ID.web.app/file2
• https://SITE_ID.web.app/file3

These files are also accessible on URLs associated with yourSITE_ID.firebaseapp.com domain.

You can also see your new release listed in theHosting dashboard of theFirebase console.