Mengelola spesifikasi API

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Dokumen ini menjelaskan cara mengelola spesifikasi API di API Hub. Lihat juga Pengantar spesifikasi API.

Menambahkan spesifikasi API ke versi

Anda dapat menambahkan satu atau beberapa spesifikasi API ke versi API. Pilih dari opsi berikut:

Menambahkan spesifikasi saat Anda membuat versi

Hanya dengan menggunakan UI, Anda dapat menambahkan spesifikasi API sekaligus membuat versi. Anda dapat memberikan URL ke spesifikasi yang dapat diakses atau mengupload file spesifikasi langsung dari sistem Anda.

Konsol

Untuk menambahkan spesifikasi ke versi baru:

  1. Ikuti langkah-langkah yang tercantum di Membuat versi API untuk memulai. Saat membuka halaman Tambahkan versi baru, Anda dapat menambahkan file spesifikasi ke versi tersebut secara opsional:
    1. Masukkan nama tampilan untuk file spesifikasi. Anda dapat menggunakan nama apa pun yang Anda inginkan.
    2. Pilih jenis file spesifikasi. Jenis spesifikasi adalah atribut sistem yang dapat dikonfigurasi. Lihat juga Atribut sistem.
    3. Berikan URI yang mengarah ke file spesifikasi API yang valid dan Anda memiliki akses ke file tersebut, atau jelajahi file spesifikasi API di sistem Anda.
    4. (Opsional) Jika Anda ingin menerapkan validasi ketat ke spesifikasi yang diupload, centang kotak Batasi upload file spesifikasi yang berisi error. Jika opsi ini dipilih, spec yang berisi error validasi tidak akan diupload. Secara default, spesifikasi yang berisi error akan diupload.
  2. Isi halaman Tambahkan versi baru, lalu klik Buat setelah selesai.

Menambahkan spesifikasi ke versi yang ada

Anda dapat menggunakan UI atau REST API untuk menambahkan spesifikasi API ke versi yang ada.

Konsol

Untuk menambahkan spesifikasi langsung ke versi:

  1. Di konsol Google Cloud, buka halaman API hub.

    Buka hub API
  2. Klik API.
  3. Temukan API dengan versi yang ingin Anda ubah. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Telusuri untuk menemukan API.
  4. Pilih API.
  5. Klik Tambahkan file spesifikasi.
  6. Masukkan nama tampilan untuk file spesifikasi. Anda dapat menggunakan nama apa pun yang Anda inginkan.
  7. Pilih jenis file spesifikasi. Jenis spesifikasi adalah atribut sistem yang dapat dikonfigurasi. Lihat juga Atribut sistem.
  8. Berikan URI yang mengarah ke file spesifikasi API yang valid dan Anda memiliki akses ke file tersebut, atau jelajahi file spesifikasi API di sistem Anda.
  9. (Opsional) Jika Anda ingin menerapkan validasi ketat ke spesifikasi yang diupload, centang kotak Batasi upload file spesifikasi yang berisi error. Jika opsi ini dipilih, spec yang berisi error validasi tidak akan diupload. Secara default, spesifikasi yang berisi error akan diupload.
  10. Pilih versi yang akan ditambahkan file spesifikasinya.
  11. Klik Create.

REST

Untuk menambahkan spesifikasi API ke versi, gunakan API Tambahkan spesifikasi API:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Ganti kode berikut:

  • API_PROJECT: Nama project host hub API Anda. Project host dipilih saat API hub disediakan.
  • API_LOCATION: Lokasi project host. Lokasi dipilih saat hub API disediakan.
  • API_ID: ID unik resource API.
  • VERSION_ID: ID versi yang dilampirkan ke resource API.
  • SPEC_ID: (Opsional) ID spesifikasi. Jika tidak diberikan, ID yang dihasilkan sistem akan digunakan. Nama harus berupa string 4-63 karakter, dengan karakter yang valid adalah /[a-z][0-9]-/.
  • DATA_FILE or URI: File yang dienkode Base64 yang berisi spesifikasi API yang valid atau link ke spesifikasi. Lihat contoh REST.

Contoh REST

Dalam contoh ini, buat spesifikasi baru di API Hub dengan spesifikasi OpenAPI yang dienkode Base64. Setelah diupload, API Hub akan mengurai spesifikasi dan membuat entitas spesifikasi baru yang menyertakan metadata deskriptif serta kumpulan entitas operasi dan definisi. 

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Contoh output:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

Untuk menampilkan detail spesifikasi:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Mencantumkan spesifikasi

Bagian ini menjelaskan cara mencantumkan spesifikasi yang terkait dengan versi API.

Konsol

Untuk mencantumkan spesifikasi dengan UI:

  1. Di konsol Google Cloud, buka halaman API hub.

    Buka hub API
  2. Klik API.
  3. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Telusuri untuk menemukan API.
  4. Klik API untuk melihat detailnya.
  5. Di tab Versions, cari versi yang ingin Anda periksa.
  6. Pilih versi.
  7. Setiap spesifikasi yang ditautkan ke versi tersebut akan dicantumkan di bagian File spesifikasi.

REST

Untuk mencantumkan spesifikasi yang terkait dengan versi API, gunakan List specifications API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ganti kode berikut:

  • HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat API hub disediakan.
  • HUB_LOCATION: Lokasi project host. Lokasi dipilih saat hub API disediakan.
  • API_ID: ID unik resource API.
  • VERSION_ID: ID unik versi.

Mendapatkan detail spesifikasi

Bagian ini menjelaskan cara mendapatkan detail tentang spesifikasi API yang terkait dengan versi.

Konsol

Untuk melihat detail spesifikasi menggunakan UI:

  1. Di konsol Google Cloud, buka halaman API hub.

    Buka hub API
  2. Klik API.
  3. Temukan API dengan versi yang berisi spesifikasi yang ingin Anda periksa. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Telusuri untuk menemukan API.
  4. Klik API untuk melihat detailnya.
  5. Di tab Versions, cari versi yang ingin Anda periksa.
  6. Pilih versi.
  7. Di bagian File spesifikasi, pilih spesifikasi untuk melihat detailnya.

REST

Untuk melihat detail spesifikasi, gunakan API Get specification details:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ganti kode berikut:

  • HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat API hub disediakan.
  • HUB_LOCATION: Lokasi project host. Lokasi dipilih saat hub API disediakan.
  • API_ID: ID unik resource API.
  • VERSION_ID: ID unik versi.
  • SPEC_ID: ID unik spesifikasi.

Contoh output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

Menghapus spesifikasi API

Bagian ini menjelaskan cara menghapus spesifikasi API dari versi. Menghapus spesifikasi juga akan menghapus operasi terkait dari versi.

Konsol

Untuk menghapus resource API dengan UI:

  1. Di konsol Google Cloud, buka halaman API hub.

    Buka hub API
  2. Klik API.
  3. Temukan API dengan versi yang berisi spesifikasi yang ingin Anda hapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Telusuri untuk menemukan API.
  4. Klik API untuk melihat detailnya.
  5. Di tab Versions, temukan versi yang berisi spesifikasi yang ingin Anda hapus.
  6. Pilih versi.
  7. Di bagian File spesifikasi, pilih Hapus dari menu Tindakan di baris spesifikasi yang ingin Anda hapus.
  8. Klik Hapus.

REST

Untuk menghapus resource API dari API Hub, gunakan API Delete API resource:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Ganti kode berikut:

  • HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat API hub disediakan.
  • HUB_LOCATION: Lokasi project host. Lokasi dipilih saat hub API disediakan.
  • API_ID: ID unik resource API.
  • VERSION_ID: ID unik versi.
  • SPEC_ID: ID unik spesifikasi yang akan dihapus.

Mengedit metadata spesifikasi

Anda dapat mengedit beberapa metadata yang terkait dengan spesifikasi yang disimpan di API Hub. Untuk mengetahui daftar metadata yang dapat Anda edit, lihat Spec patch API.

Konsol

Anda dapat melakukan perubahan pada spesifikasi yang ada melalui konsol Google Cloud. Misalnya, Anda dapat mengubah nama tampilan, mengupload file spesifikasi baru, mengubah jenis file, dan mengedit atribut:

  1. Di konsol Google Cloud, buka halaman API hub.

    Buka hub API
  2. Klik API.
  3. Temukan API dengan versi yang berisi spesifikasi yang ingin Anda edit. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Telusuri untuk menemukan API.
  4. Klik API untuk melihat detailnya.
  5. Di tab Versions, cari versi yang berisi spesifikasi yang ingin Anda edit.
  6. Pilih versi.
  7. Di halaman Versi, temukan spesifikasi yang ingin diedit.
  8. Pilih Edit dari menu Actions di baris spesifikasi yang ingin Anda edit.
  9. Di panel pengeditan spesifikasi, Anda dapat mengubah metadata spesifikasi berikut:
    • Nama tampilan
    • Jenis file spesifikasi
    • Dokumen spesifikasi: Jelajahi file spesifikasi baru yang akan diupload.
    • (Opsional) Jika Anda ingin menerapkan validasi ketat ke spesifikasi yang diupload, centang kotak Batasi upload file spesifikasi yang berisi error. Jika opsi ini dipilih, spec yang berisi error validasi tidak akan diupload. Secara default, spesifikasi yang berisi error akan diupload.
    • Atribut yang ditentukan pengguna (jika ada)
  10. Klik Simpan.

REST

Untuk mengedit spesifikasi dengan REST API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Ganti kode berikut:

  • HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat API hub disediakan.
  • HUB_LOCATION: Lokasi project host. Lokasi dipilih saat hub API disediakan.
  • API_ID: ID unik resource API.
  • VERSION_ID: ID unik versi.
  • SPEC_ID: ID unik spesifikasi.
  • Request Body: Gunakan isi permintaan untuk menentukan atribut yang akan diubah. Lihat Definisi resource spesifikasi.

Melihat hasil lint spesifikasi

API hub menyediakan lint (validator) bawaan (Spectral) yang memvalidasi spesifikasi Open API API Anda. Lihat Memvalidasi spesifikasi API.

  1. Di konsol Google Cloud, buka halaman API hub.

    Buka hub API
  2. Klik API.
  3. Temukan API dengan versi yang berisi spesifikasi yang ingin Anda periksa. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Telusuri untuk menemukan API.
  4. Klik API untuk melihat detailnya.
  5. Di tab Versions, cari versi yang berisi spesifikasi yang ingin Anda periksa.
  6. Klik Lihat Hasil di kolom Hasil lint untuk melihat hasil lint.

Mendapatkan konten spesifikasi

Fitur ini memungkinkan Anda meninjau konten spesifikasi yang diupload ke API Hub.

Konsol

Untuk melihat detail spesifikasi menggunakan UI:

  1. Di konsol Google Cloud, buka halaman API hub.

    Buka hub API
  2. Klik API.
  3. Temukan API dengan versi yang berisi spesifikasi yang ingin Anda hapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Telusuri untuk menemukan API.
  4. Klik API untuk melihat detailnya.
  5. Di tab Versions, cari versi yang berisi spesifikasi yang ingin Anda periksa.
  6. Klik nama spesifikasi untuk melihat kontennya.

REST

API mengambil konten mentah yang dienkode Base64 dari spesifikasi API yang diupload ke API Hub. Gunakan API Get specification contents:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ganti kode berikut:

  • HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat API hub disediakan.
  • HUB_LOCATION: Lokasi project host. Lokasi dipilih saat hub API disediakan.
  • API_ID: ID unik resource API.
  • VERSION_ID: ID unik versi.
  • SPEC_ID: ID unik spesifikasi.

Contoh output:

{
  "contents": "Base64-encoded file contents"
}