This AIP is currently a draft. This means that it is being actively debated and discussed, and it may change in non-trivial ways.

AIP-2718

References to objects in other APIs

Your API may need to refer to objects in other APIs. For example, a Sheets cell may want to refer to the Slides deck that explains its meaning. This kind of cross reference should be as natural to use as possible with the target API.

Guidance

When your API refers to an object accessed via another API (the "target" API), the reference your API provides depends upon whether the reference is compliant with One Platform or not.

• If a field always holds a compliant reference to a single specific target API, the reference you provide must be a relative URI from the top level of the target API's naming hierarchy. For example, if the full URL of the object is https://koalas.googleapis.com/koalas/123435 the reference you return to it must be the relative URI koalas/123435. Further, your documentation must make clear that the reference is used with koalas.googleapis.com.

  This provides the developer with a natural way to use the reference, using the returned path directly. It also ensures that they know which API understands that reference.

• If a field always holds a compliant reference, but is not limited to a single target API, the reference you provide must be a relative URI that includes the path of its specific target API, such as koalas.googleapis.com/koalas/123435. This provides the developer with the correct target in a formalized, usable way.

• Otherwise, the reference you return must be chosen to be as natural to use as possible with the target API, and the API and its version must be documented. For example, if the Apiary-based Koala API uses an ID in its GetKoalaData method, you must return the ID that can be used as a parameter, as well as documenting that you are using IDs that work in Koala API 1.0.

Naming

For compliant references, you should avoid the use of the terms "reference" and "name" in the field name. That is, koala is preferred to koala_reference or koala_name (see [AIP-122](/122)).

For other target APIs, you should echo that API's terminology in the name for clarity. For example, if the target API's GetKoalaDataRequest has a koala_num field, your field name should probably be koala_num, or it would include koala_num in its name, such as responsible_koala_num.