Skip to content

api: require *_time suffix on Timestamp fields and rename expires_at and take_golden_snapshot_at #2415

Closed

Description

In pkg/proto/ateapipb/ateapi.proto, most google.protobuf.Timestamp fields follow AIP-142 (*_time suffix, noun phrase without verbs or prepositions):

  • ObjectMeta.create_time
  • ObjectMeta.update_time
  • ActorCrash.crash_time

Two Timestamp fields deviate from this convention and violate docs/api-style-guide.md §5 ("Field names must be nouns, not verbs", "Avoid prepositions in field names"):

  1. MintActorJWTResponse.expires_at (ateapi.proto:1745): uses a verb + preposition (expires_at) instead of expire_time (the standard name used across GCP's STS and IAM Credentials APIs for Timestamp expiration fields, per AIP-142 / AIP-214).
  2. GoldenSnapshotStatus.take_golden_snapshot_at (ateapi.proto:1028): starts with a verb (take_) and ends with a preposition (_at).

Additionally, while docs/api-style-guide.md §6 references AIP-142 for create_time and update_time, §5 ("Field Naming") does not explicitly state that google.protobuf.Timestamp fields must end with _time.

Proposal

  1. In docs/api-style-guide.md §5 ("Field Naming"), add an explicit rule (citing AIP-142) requiring google.protobuf.Timestamp fields to end with _time (e.g., create_time, expire_time, crash_time, not created_at or expires_at).
  2. In pkg/proto/ateapipb/ateapi.proto:
    • Rename MintActorJWTResponse.expires_at to expire_time.
    • Rename GoldenSnapshotStatus.take_golden_snapshot_at to snapshot_time.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/apiUser-facing API changeskind/cleanupSmall fixes that are not bugs, for example a typo in a code comment

    Type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions