目錄結構

典型的 API 目錄包含 .proto 檔案 (定義 API 介面) 和 .yaml 檔案 (設定 API 服務)。使用這個版面配置有助於在各個環境中，維持一致的服務設定和版本化介面。每個 API 服務必須在 API 存放區內有 API 目錄，且 API 目錄應包含所有 API 定義檔案和建構指令碼。

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

• API 目錄

  • 存放區必要項目

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

  • 設定檔

    • {service}.yaml - 基準服務設定檔，也就是 google.api.Service proto 訊息的 YAML 表示法。
    • prod.yaml - The prod delta service config file.
    • 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 APIs」存放區。