Package google.digitalassetlinks.v1

Index

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(ListRequest) returns (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. 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 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 WebAsset Set if this is a web asset.
android_app 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 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 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 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 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 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 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 Statement A list of all the matching statements that have been found.
max_age 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.

Field name Type Description
source 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 for the current list of supported relations.

Example: delegate_permission/common.handle_all_urls REQUIRED
target 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