# Package google.digitalassetlinks.v1

## Index

- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.AssetLinks` (interface)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Statements` (interface)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.AndroidAppAsset` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.AndroidAppAsset.CertificateInfo` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Asset` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.CheckRequest` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.CheckResponse` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.ListRequest` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.ListResponse` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Statement` (message)
- `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.WebAsset` (message)

## AssetLinks

This API service gives access to "asset links". Each asset link represents a single directional relationship between a source asset and a target asset. The nature of the relationship is given by a "relation" string. A given pair of source and target assets may be linked by multiple relations.

Clients use this API to answer specific questions about the intents that asset owners expressed about the relationship between two assets.

Note that asset links are not transitive: If assets A and B are linked for a given relation and assets B and C are linked for the same relation, that does not imply that assets A and C are linked.

| Check |
|---|
| `` rpc Check(`https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.CheckRequest`) returns (`https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.CheckResponse`) `` Determines whether the specified (directional) relationship exists between the specified source and target assets. The relation describes the intent of the link between the two assets as claimed by the source asset. An example for such relationships is the delegation of privileges or permissions. This command is most often used by infrastructure systems to check preconditions for an action. For example, a client may want to know if it is OK to send a web URL to a particular mobile app instead. The client can check for the relevant asset link from the website to the mobile app to decide if the operation should be allowed. A note about security: if you specify a secure asset as the source, such as an HTTPS website or an Android app, the API will ensure that any statements used to generate the response have been made in a secure way by the owner of that asset. Conversely, if the source asset is an insecure HTTP website (that is, the URL starts with `http://` instead of `https://`), the API cannot verify its statements securely, and it is not possible to ensure that the website's statements have not been altered by a third party. For more information, see the [Digital Asset Links technical design specification](https://github.com/google/digitalassetlinks/blob/master/well-known/details.md). |

## Statements

This API service serves "statements", which are the vehicles used by asset owners to publish information about their asset links. The API can be used to retrieve statements in a simple and secure way, without the need to acquire the statements directly from the sources.

All statements returned by this API have been made on behalf of digital assets (for example, websites or Android apps) about other digital assets. Each statement contains a source asset, a target asset and one or more relations.

The relation describes the relationship between the two assets as claimed by the source asset. An example for such relationships is the delegation of privileges or permissions.

| List |
|---|
| `` rpc List(`https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.ListRequest`) returns (`https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.ListResponse`) `` Retrieves a list of all statements from a given source that match the specified target and statement string. The API guarantees that all statements with secure source assets, such as HTTPS websites or Android apps, have been made in a secure way by the owner of those assets, as described in the [Digital Asset Links technical design specification](https://github.com/google/digitalassetlinks/blob/master/well-known/details.md). Specifically, you should consider that for insecure websites (that is, where the URL starts with `http://` instead of `https://`), this guarantee cannot be made. The `List` command is most useful in cases where the API client wants to know all the ways in which two assets are related, or enumerate all the relationships from a particular source asset. Example: a feature that helps users navigate to related items. When a mobile app is running on a device, the feature would make it easy to navigate to the corresponding web site or Google+ profile. |

## AndroidAppAsset

Describes an android app asset.

| Field name | Type | Description |
|---|---|---|
| `package_name` | `string` | Android App assets are naturally identified by their Java package name. For example, the Google Maps app uses the package name `com.google.android.apps.maps`. REQUIRED |
| `certificate` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.AndroidAppAsset.CertificateInfo` `` | Because there is no global enforcement of package name uniqueness, we also require a signing certificate, which in combination with the package name uniquely identifies an app. Some apps' signing keys are rotated, so they may be signed by different keys over time. We treat these as distinct assets, since we use (package name, cert) as the unique ID. This should not normally pose any problems as both versions of the app will make the same or similar statements. Other assets making statements about the app will have to be updated when a key is rotated, however. (Note that the syntaxes for publishing and querying for statements contain syntactic sugar to easily let you specify apps that are known by multiple certificates.) REQUIRED |

## CertificateInfo

Describes an X509 certificate.

| Field name | Type | Description |
|---|---|---|
| `sha256_fingerprint` | `string` | The uppercase SHA-265 fingerprint of the certificate. From the PEM certificate, it can be acquired like this: $ keytool -printcert -file $CERTFILE | grep SHA256: SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \ 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5 or like this: $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256 SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \ 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5 In this example, the contents of this field would be `14:6D:E9:83:C5:73: 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF: 44:E5`. If these tools are not available to you, you can convert the PEM certificate into the DER format, compute the SHA-256 hash of that string and represent the result as a hexstring (that is, uppercase hexadecimal representations of each octet, separated by colons). |

## Asset

Uniquely identifies an asset.

A digital asset is an identifiable and addressable online entity that typically provides some service or content. Examples of assets are websites, Android apps, Twitter feeds, and Plus Pages.

| Field name | Type | Description |
|---|---|---|
| Union field, only one of the following: |||
| `web` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.WebAsset` `` | Set if this is a web asset. |
| `android_app` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.AndroidAppAsset` `` | Set if this is an Android App asset. |

## CheckRequest

Message used to check for the existence of a specific asset link.

| Field name | Type | Description |
|---|---|---|
| `source` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Asset` `` | The source hosting the statement list. This is used to route the `Check()` call to the proper source. |
| `relation` | `string` | Query string for the relation. We identify relations with strings of the format `<kind>/<detail>`, where `<kind>` must be one of a set of pre-defined purpose categories, and `<detail>` is a free-form lowercase alphanumeric string that describes the specific use case of the statement. Refer to [our API documentation](https://developers.google.com/digital-asset-links/v1/relation-strings) for the current list of supported relations. For a query to match an asset link, both the query's and the asset link's relation strings must match exactly. Example: A query with relation `delegate_permission/common.handle_all_urls` matches an asset link with relation `delegate_permission/common.handle_all_urls`. |
| `target` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Asset` `` | The target asset of the statement. |

## CheckResponse

Response message for the CheckAssetLinks call.

| Field name | Type | Description |
|---|---|---|
| `linked` | `bool` | Set to true if the assets specified in the request are linked by the relation specified in the request. REQUIRED |
| `max_age` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.protobuf#google.protobuf.Duration` `` | From serving time, how much longer the response should be considered valid barring further updates. REQUIRED |
| `debug_string` | `string` | Human-readable message containing information intended to help end users understand, reproduce and debug the result. The message will be in English and we are currently not planning to offer any translations. Please note that no guarantees are made about the contents or format of this string. Any aspect of it may be subject to change without notice. You should not attempt to programmatically parse this data. If you feel that you need to do this because the information you need is not otherwise exposed by the API, please contact us first. |

## ListRequest

Message used to request all known statements that have a specified source and relation.

| Field name | Type | Description |
|---|---|---|
| `source` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Asset` `` | The source hosting the statement list. This is used to direct the `List()` request to the right source. REQUIRED |
| `relation` | `string` | Use only associations that match the specified relation. See the [`Statement`](https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#Statement) message for a detailed definition of relation strings. For a query to match a statement, one of the following must be true: - both the query's and the statement's relation strings match exactly, or - the query's relation string is empty or missing. Example: A query with relation `delegate_permission/common.handle_all_urls` matches an asset link with relation `delegate_permission/common.handle_all_urls`. |

## ListResponse

Response message for the List call.

| Field name | Type | Description |
|---|---|---|
| `statements` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Statement` `` | A list of all the matching statements that have been found. |
| `max_age` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.protobuf#google.protobuf.Duration` `` | From serving time, how much longer the response should be considered valid barring further updates. REQUIRED |
| `debug_string` | `string` | Human-readable message containing information intended to help end users understand, reproduce and debug the result. The message will be in English and we are currently not planning to offer any translations. Please note that no guarantees are made about the contents or format of this string. Any aspect of it may be subject to change without notice. You should not attempt to programmatically parse this data. If you feel that you need to do this because the information you need is not otherwise exposed by the API, please contact us first. |

## Statement

Describes a reliable statement that has been made about the relationship between a source asset and a target asset.

Statements are always made by the source asset, either directly or by delegating to a statement list that is stored elsewhere.

For more detailed definitions of statements and assets, please refer to our [API documentation landing page](https://developers.google.com/digital-asset-links/v1/getting-started).

| Field name | Type | Description |
|---|---|---|
| `source` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Asset` `` | Every statement has a source asset. REQUIRED |
| `relation` | `string` | The relation identifies the use of the statement as intended by the source asset's owner (that is, the person or entity who issued the statement). Every complete statement has a relation. We identify relations with strings of the format `<kind>/<detail>`, where `<kind>` must be one of a set of pre-defined purpose categories, and `<detail>` is a free-form lowercase alphanumeric string that describes the specific use case of the statement. Refer to [our API documentation](https://developers.google.com/digital-asset-links/v1/relation-strings) for the current list of supported relations. Example: `delegate_permission/common.handle_all_urls` REQUIRED |
| `target` | `` `https://developers.google.com/digital-asset-links/reference/rpc/google.digitalassetlinks.v1#google.digitalassetlinks.v1.Asset` `` | Every statement has a target asset. REQUIRED |

## WebAsset

Describes a web asset.

| Field name | Type | Description |
|---|---|---|
| `site` | `string` | Web assets are identified by a URL that contains only the scheme, hostname and port parts. The format is http[s]://<hostname>[:<port>] Hostnames must be fully qualified: they must end in a single period ("`.`"). Only the schemes "http" and "https" are currently allowed. Port numbers are given as a decimal number, and they must be omitted if the standard port numbers are used: 80 for http and 443 for https. We call this limited URL the "site". All URLs that share the same scheme, hostname and port are considered to be a part of the site and thus belong to the web asset. Example: the asset with the site `https://www.google.com` contains all these URLs: - `https://www.google.com/` - `https://www.google.com:443/` - `https://www.google.com/foo` - `https://www.google.com/foo?bar` - `https://www.google.com/foo#bar` - `https://user@password:www.google.com/` But it does not contain these URLs: - `http://www.google.com/` (wrong scheme) - `https://google.com/` (hostname does not match) - `https://www.google.com:444/` (port does not match) REQUIRED |