目錄結構

API 服務通常是使用 .proto 檔案來定義 API 介面，並使用 .yaml 檔案來設定 API 服務。每個 API 服務都必須在 API 存放區中設置一個 API 目錄。API 目錄應包含所有 API 定義檔案和建構指令碼。

每個 API 目錄都應具有以下標準配置：

• API 目錄

  • 存放區必要項目

    • BUILD：建構檔案。
    • METADATA：建構中繼資料檔案。
    • OWNERS：API 目錄擁有者。
    • README.md：API 服務的一般資訊。

  • 設定檔

    • {service}.yaml：基準服務設定檔，為採 YAML 表示法的 google.api.Service proto 訊息。
    • prod.yaml：實際工作環境 delta 服務設定檔。
    • staging.yaml：測試環境 delta 服務設定檔。
    • test.yaml：測試 delta 服務設定檔。
    • local.yaml：本機 delta 服務設定檔。

  • 說明文件檔案

    • doc/*：技術說明文件檔案，應採 Markdown 格式。

  • 介面定義

    • v[0-9]*/*：每個這類目錄都包含 API 的主要版本，主要是 proto 檔案和建構指令碼。
    • {subapi}/v[0-9]*/*：每個 {subapi} 目錄都包含子 API 的介面定義。每個子 API 都可有自己的獨立主要版本。
    • type/*：proto 檔案，其中包含不同 API 或相同 API 的不同版本共用的類型，或 API 和服務實作共用的類型。type/* 底下的型別定義不應在發布時造成破壞性變更。

公開的 Google API 定義會發布在 GitHub 上，請參閱 Google API 存放區。