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.
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/123435the reference you return to it must be the relative URI
koalas/123435. Further, your documentation must make clear that the reference is used with
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
GetKoalaDatamethod, 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.
For compliant references, you should avoid the use of the terms “reference”
and “name” in the field name. That is,
koala is preferred to
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
koala_num in its name, such as