In services that have model objects with "id" as a field, we try to differentiate between that "id" field and the "identity" of that object (the information necessary to reconstruct/access that object via the service). For example, blobs have "id" fields, but gcloud-java-storage also has a BlobId class that contains the bucket name, blob name, and generation.
In the javadoc, we use "identity" to describe classes like BlobId. I feel that "reference" is a slightly better word than "identity" because "reference" is a more commonly used word and thus would make the javadoc read more nicely. Also, "id" is a shorthand for "identity" (and a user could potentially assume they're related), whereas "reference" might differentiate the two items more clearly.
In services that have model objects with "id" as a field, we try to differentiate between that "id" field and the "identity" of that object (the information necessary to reconstruct/access that object via the service). For example, blobs have "id" fields, but
gcloud-java-storagealso has aBlobIdclass that contains the bucket name, blob name, and generation.In the javadoc, we use "identity" to describe classes like
BlobId. I feel that "reference" is a slightly better word than "identity" because "reference" is a more commonly used word and thus would make the javadoc read more nicely. Also, "id" is a shorthand for "identity" (and a user could potentially assume they're related), whereas "reference" might differentiate the two items more clearly.