## Resource: Domain

A domain name that is associated with a backend.

| JSON representation |
|---|
| ``` { "name": string, "displayName": string, "createTime": string, "updateTime": string, "type": enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.Type`), "disabled": boolean, "serve": { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.ServingBehavior`) }, "customDomainStatus": { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.CustomDomainStatus`) }, "reconciling": boolean, "deleteTime": string, "purgeTime": string, "labels": { string: string, ... }, "annotations": { string: string, ... }, "uid": string, "etag": string } ``` |

| Fields ||
|---|---|
| `name` | `string` Identifier. The resource name of the domain, e.g. `/projects/p/locations/l/backends/b/domains/foo.com` |
| `displayName` | `string` Optional. Mutable human-readable name for the domain. 63 character limit. e.g. `prod domain`. |
| `createTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Time at which the domain was created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `updateTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Time at which the domain was last updated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `type` | ``enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.Type`)`` Output only. The type of the domain. |
| `disabled` | `boolean` Optional. Whether the domain is disabled. Defaults to false. |
| `serve` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.ServingBehavior`)`` Optional. The serving behavior of the domain. If specified, the domain will serve content other than its backend's live content. |
| `customDomainStatus` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.CustomDomainStatus`)`` Output only. Represents the state and configuration of a `CUSTOM` type domain. It is only present on Domains of that type. |
| `reconciling` | `boolean` Output only. A field that, if true, indicates that the build has an ongoing LRO. |
| `deleteTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Time at which the domain was deleted. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `purgeTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Time at which a soft-deleted domain will be purged, rendering in permanently deleted. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `labels` | `map (key: string, value: string)` Optional. Labels as key value pairs. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `annotations` | `map (key: string, value: string)` Optional. Annotations as key value pairs. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `uid` | `string` Output only. System-assigned, unique identifier. |
| `etag` | `string` Output only. Server-computed checksum based on other values; may be sent on update or delete to ensure operation is done on expected resource. |

## Domain.Type

The type of the domain.

| Enums ||
|---|---|
| `TYPE_UNSPECIFIED` | The type is unspecified (this should not happen). |
| `DEFAULT` | Default, App Hosting-provided and managed domains. These domains are created automatically with their parent backend and cannot be deleted except by deleting that parent, and cannot be moved to another backend. Default domains can be disabled via the `disabled` field. |
| `CUSTOM` | Custom, developer-owned domains. Custom Domains allow you to associate a domain you own with your App Hosting backend, and configure that domain to serve your backend's content. |

## Domain.ServingBehavior

Indicates whether App Hosting will serve content on the domain.

| JSON representation |
|---|
| ``` { // Union field `serving_behavior` can be only one of the following: "redirect": { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.ServingBehavior.Redirect`) } // End of list of possible types for union field `serving_behavior`. } ``` |

| Fields ||
|---|---|
| Union field `serving_behavior`. If specified, customizes the serving behaviour of a domain. `serving_behavior` can be only one of the following: ||
| `redirect` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#Domain.ServingBehavior.Redirect`)`` Optional. Redirect behavior for a domain, if provided. |

## Domain.ServingBehavior.Redirect

Specifies redirect behavior for a domain.

| JSON representation |
|---|
| ``` { "uri": string, "status": string } ``` |

| Fields ||
|---|---|
| `uri` | `string` Required. The URI of the redirect's intended destination. This URI will be prepended to the original request path. URI without a scheme are assumed to be HTTPS. |
| `status` | `string (https://developers.google.com/discovery/v1/type-format format)` Optional. The status code to use in a redirect response. Must be a valid HTTP 3XX status code. Defaults to 302 if not present. |

## Domain.CustomDomainStatus

The status of a custom domain's linkage to a backend.

| JSON representation |
|---|
| ``` { "hostState": enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#HostState`), "ownershipState": enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#OwnershipState`), "certState": enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#CertState`), "requiredDnsUpdates": [ { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsUpdates`) } ], "issues": [ { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1/Status`) } ] } ``` |

| Fields ||
|---|---|
| `hostState` | ``enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#HostState`)`` Output only. Tracks whether a custom domain is detected as appropriately directing traffic to App Hosting. |
| `ownershipState` | ``enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#OwnershipState`)`` Output only. Tracks whether the backend is permitted to serve content on the domain, based off the domain's DNS records. |
| `certState` | ``enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#CertState`)`` Output only. Tracks SSL certificate status for the domain. |
| `requiredDnsUpdates[]` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsUpdates`)`` Output only. Lists the records that must added or removed to a custom domain's DNS in order to finish setup and start serving content. Field is present during onboarding. Also present after onboarding if one or more of the above states is not \*_ACTIVE, indicating the domain's DNS records are in a bad state. |
| `issues[]` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1/Status`)`` Output only. A list of issues with domain configuration. Allows users to self-correct problems with DNS records. |

## HostState

The host state of your domain. Host state is determined by checking each IP address associated with your domain to see if it's serving through the appropriate shard of App Hosting's Origin.

| Enums ||
|---|---|
| `HOST_STATE_UNSPECIFIED` | Your custom domain's host state is unspecified. The message is invalid if this is unspecified. |
| `HOST_UNHOSTED` | Your custom domain isn't associated with any IP addresses. |
| `HOST_UNREACHABLE` | Your custom domain can't be reached. App Hosting services' DNS queries to find your domain's IP addresses resulted in errors. See your `CustomDomainStatus`'s `issues` field for more details. |
| `HOST_NON_FAH` | Your domain has only IP addresses that don't ultimately resolve to App Hosting. |
| `HOST_CONFLICT` | Your domain has IP addresses that resolve to both App Hosting and to other services. To ensure consistent results, remove `A` and `AAAA` records related to non-App-Hosting services. |
| `HOST_WRONG_SHARD` | Your domain has IP addresses that resolve to an incorrect instance of the App Hosting Data Plane. App Hosting has multiple data plane instances to ensure high availability. The SSL certificate that App Hosting creates for your domain is only available on its assigned instance. If your domain's IP addresses resolve to an incorrect instance, App Hosting won't be able to serve secure content on it. |
| `HOST_ACTIVE` | All requests against your domain are served by App Hosting, via your domain's assigned shard. If the custom domain's `OwnershipState` is also `OWNERSHIP_ACTIVE`, App Hosting serves its backend's content on requests for the domain. |

## OwnershipState

The ownership state of your custom domain.

| Enums ||
|---|---|
| `OWNERSHIP_STATE_UNSPECIFIED` | Your custom domain's ownership state is unspecified. This should never happen. |
| `OWNERSHIP_MISSING` | Your custom domain's domain has no App-Hosting-related ownership records; no backend is authorized to serve on the domain in this Origin shard. |
| `OWNERSHIP_UNREACHABLE` | Your custom domain can't be reached. App Hosting services' DNS queries to find your domain's ownership records resulted in errors. See your `CustomDomainStatus`'s `issues` field for more details. |
| `OWNERSHIP_MISMATCH` | Your custom domain is owned by another App Hosting custom domain. Remove the conflicting records and replace them with records for your current custom domain. |
| `OWNERSHIP_CONFLICT` | Your custom domain has conflicting `TXT` records that indicate ownership by both your current custom domain one or more others. Remove the extraneous ownership records to grant the current custom domain ownership. |
| `OWNERSHIP_PENDING` | Your custom domain's DNS records are configured correctly. App Hosting will transfer ownership of your domain to this custom domain within 24 hours. |
| `OWNERSHIP_ACTIVE` | Your custom domain owns its domain. |

## CertState

The state of the SSL certificate App Hosting has for your domain name. This can represent either the state of the actual certificate or, for new custom domains, App Hosting's in-progress attempt to create a certificate.

| Enums ||
|---|---|
| `CERT_STATE_UNSPECIFIED` | The certificate's state is unspecified. The message is invalid if this is unspecified. |
| `CERT_PREPARING` | The initial state of every certificate, represents App Hosting's intent to create a certificate before requests to a Certificate Authority are made. |
| `CERT_VALIDATING` | App Hosting is validating whether a domain name's DNS records are in a state that allow certificate creation on its behalf. |
| `CERT_PROPAGATING` | The certificate was recently created, and needs time to propagate in App Hosting's load balancers. |
| `CERT_ACTIVE` | The certificate is active, providing secure connections for the domain names it represents. |
| `CERT_EXPIRING_SOON` | The certificate is expiring, all domain names on it will be given new certificates. |
| `CERT_EXPIRED` | The certificate has expired. App Hosting can no longer serve secure content on your domain name. |

## DnsUpdates

A set of DNS record updates that you should make to allow App Hosting to serve secure content in response to requests against your domain. These updates present the current state of your domain's and related subdomains' DNS records when App Hosting last queried them, and the desired set of records that App Hosting needs to see before your custom domain can be fully active.

| JSON representation |
|---|
| ``` { "domainName": string, "discovered": [ { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecordSet`) } ], "desired": [ { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecordSet`) } ], "checkTime": string } ``` |

| Fields ||
|---|---|
| `domainName` | `string` Output only. The domain name the DNS updates pertain to. |
| `discovered[]` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecordSet`)`` Output only. The set of DNS records App Hosting discovered when inspecting a domain. |
| `desired[]` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecordSet`)`` Output only. The set of DNS records App Hosting needs in order to be able to serve secure content on the domain. |
| `checkTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. The last time App Hosting checked your custom domain's DNS records. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |

## DnsRecordSet

A set of DNS records relevant to the setup and maintenance of a custom domain in App Hosting.

| JSON representation |
|---|
| ``` { "domainName": string, "checkError": { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1/Status`) }, "records": [ { object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecord`) } ] } ``` |

| Fields ||
|---|---|
| `domainName` | `string` Output only. The domain name the record set pertains to. |
| `checkError` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1/Status`)`` Output only. An error App Hosting services encountered when querying your domain's DNS records. Note: App Hosting ignores `NXDOMAIN` errors, as those generally just mean that a domain name hasn't been set up yet. |
| `records[]` | ``object (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecord`)`` Output only. Records on the domain. |

## DnsRecord

A representation of a DNS records for a domain.

DNS records are resource records that define how systems and services should behave when handling requests for a domain. For example, when you add `A` records to your domain's DNS records, you're informing other systems (such as your users' web browsers) to contact those IPv4 addresses to retrieve resources relevant to your domain (such as your App Hosting files).

| JSON representation |
|---|
| ``` { "domainName": string, "type": enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecord.Type`), "rdata": string, "requiredAction": enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecord.Action`), "relevantState": [ enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#CustomDomainState`) ] } ``` |

| Fields ||
|---|---|
| `domainName` | `string` Output only. The domain the record pertains to, e.g. `foo.bar.com.`. |
| `type` | ``enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecord.Type`)`` Output only. The record's type, which determines what data the record contains. |
| `rdata` | `string` Output only. The data of the record. The meaning of the value depends on record type: - A and AAAA: IP addresses for the domain. - CNAME: Another domain to check for records. - TXT: Arbitrary text strings associated with the domain. App Hosting uses TXT records to determine which Firebase projects have permission to act on the domain's behalf. - CAA: The record's flags, tag, and value, e.g. `0 issue "pki.goog"`. |
| `requiredAction` | ``enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#DnsRecord.Action`)`` Output only. An enum that indicates the a required action for this record. Populated when the record is part of a required change in a `DnsUpdates` `discovered` or `desired` record set. |
| `relevantState[]` | ``enum (`https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains#CustomDomainState`)`` Output only. An enum that indicates which state(s) this DNS record applies to. Populated for all records with an `ADD` or `REMOVE` required action. |

## DnsRecord.Type

The type of the DNS record, including `A`, `TXT`, `AAAA`, and `CAA`.

| Enums ||
|---|---|
| `TYPE_UNSPECIFIED` | The record's type is unspecified. The message is invalid if this is unspecified. |
| `A` | An `A` record, as defined in [RFC 1035](https://tools.ietf.org/html/rfc1035). A records determine which IPv4 addresses a domain directs traffic towards. |
| `CNAME` | A `CNAME` record, as defined in [RFC 1035](https://tools.ietf.org/html/rfc1035). `CNAME` or Canonical Name records map a domain to a different, canonical domain. If a `CNAME` record is present, it should be the only record on the domain. |
| `TXT` | A `TXT` record, as defined in [RFC 1035](https://tools.ietf.org/html/rfc1035). `TXT` records hold arbitrary text data on a domain. Hosting uses `TXT` records to establish which Firebase Project has permission to act on a domain. |
| `AAAA` | An AAAA record, as defined in [RFC 3596](https://tools.ietf.org/html/rfc3596) AAAA records determine which IPv6 addresses a domain directs traffic towards. |
| `CAA` | A CAA record, as defined in [RFC 6844](https://tools.ietf.org/html/rfc6844). CAA, or Certificate Authority Authorization, records determine which Certificate Authorities (SSL certificate minting organizations) are authorized to mint a certificate for the domain. App Hosting uses `pki.goog` as its primary CA. CAA records cascade. A CAA record on `foo.com` also applies to `bar.foo.com` unless `bar.foo.com` has its own set of CAA records. CAA records are optional. If a domain and its parents have no CAA records, all CAs are authorized to mint certificates on its behalf. In general, App Hosting only asks you to modify CAA records when doing so is required to unblock SSL cert creation. |

## DnsRecord.Action

The type of action you should take on this DNS record to configure your domain for use with App Hosting.

| Enums ||
|---|---|
| `NONE` | No action necessary. |
| `ADD` | Add this record to your DNS records. |
| `REMOVE` | Remove this record from your DNS records. |

## CustomDomainState

A set of states relevant to the healthy functioning of a custom domain.

| Enums ||
|---|---|
| `CUSTOM_DOMAIN_STATE_UNSPECIFIED` | This message is invalid if this is unspecified. |
| `HOST_STATE` | The custom domain's host state. |
| `OWNERSHIP_STATE` | The custom domain's ownership state. |
| `CERT_STATE` | The custom domain's certificate state. |

| ## Methods ||
|---|---|
| ### `https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains/create` | Links a new domain to a backend. |
| ### `https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains/delete` | Deletes a single domain. |
| ### `https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains/get` | Gets information about a domain. |
| ### `https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains/list` | Lists domains of a backend. |
| ### `https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.domains/patch` | Updates the information for a single domain. |