Mengelola spesifikasi API

Konsol

Untuk menambahkan spesifikasi ke versi baru:

1. Ikuti langkah-langkah yang tercantum di Membuat versi API untuk memulai. Jika Anda buka halaman Add a new version, Anda dapat menambahkan file spesifikasi ke versi:
   1. Masukkan nama tampilan untuk file spesifikasi. Anda dapat menggunakan nama apa pun yang Anda inginkan.
   2. Pilih jenis file spesifikasi. Jenis spesifikasi adalah sistem yang dapat dikonfigurasi . Lihat juga Atribut sistem.
   3. Berikan URI yang menunjuk ke file spesifikasi API valid yang bisa Anda akses, atau cari file spesifikasi API di sistem Anda.
   4. (Opsional) Jika Anda ingin menerapkan validasi ketat pada spesifikasi yang diupload, pilih Kotak centang Batasi upload file spesifikasi yang berisi error. Ketika opsi ini dipilih, spesifikasi yang berisi error validasi tidak akan diupload. Secara {i>default<i}, spesifikasi yang berisi kesalahan telah diupload.
2. Selesaikan pengisian halaman Add a new version, lalu klik Create ketika Anda sudah selesai.

Konsol

Untuk menambahkan spesifikasi secara langsung ke versi:

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

   Buka hub API
2. Klik API.
3. Cari API dengan versi yang ingin Anda ubah. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran 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 sistem yang dapat dikonfigurasi . Lihat juga Atribut sistem.
8. Berikan URI yang mengarah ke file spesifikasi API valid yang aksesnya Anda miliki, atau cari file spesifikasi API di sistem Anda.
9. (Opsional) Jika Anda ingin menerapkan validasi ketat pada spesifikasi yang diupload, pilih Kotak centang Batasi upload file spesifikasi yang berisi error. Ketika opsi ini dipilih, spesifikasi yang berisi error validasi tidak akan diupload. Secara {i>default<i}, spesifikasi yang berisi kesalahan telah diupload.
10. Pilih versi yang akan ditambahi file spesifikasi.
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 hub API disediakan.
• API_LOCATION: Lokasi project host. Lokasi dipilih saat API telah 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 akan digunakan. Nama harus berupa string berisi 4-63 karakter, dengan karakter yang valid adalah /[a-z][0-9]-/.
• DATA_FILE or URI: File berenkode Base64 yang berisi spesifikasi API yang valid atau menautkan ke spesifikasi. Lihat contoh REST.

Contoh REST

Dalam contoh ini, buat spesifikasi baru di hub API dengan enkode Base64 Spesifikasi OpenAPI. Setelah diupload, hub API akan mengurai spesifikasi dan membuat entity spesifikasi baru yang menyertakan {i>metadata<i} deskriptif ditambah 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"
}

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 Penelusuran untuk menemukan API.
4. Klik API untuk melihat detailnya.
5. Di tab Versi, cari versi yang ingin Anda periksa.
6. Pilih versi.
7. Spesifikasi apa pun yang ditautkan ke versi tercantum di bagian File spesifikasi.

REST

Untuk mencantumkan spesifikasi yang terkait dengan versi API, gunakan API ListSpecification:

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 hub API disediakan.
• HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
• API_ID: ID unik resource API.
• VERSION_ID: ID unik 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 Penelusuran untuk menemukan API.
4. Klik API untuk melihat detailnya.
5. Di tab Versi, cari versi yang ingin Anda periksa.
6. Pilih versi.
7. Di bagian Specification file, pilih spesifikasi untuk melihat detailnya.

REST

Untuk melihat detail spesifikasi, gunakan API Mendapatkan detail spesifikasi:

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 hub API disediakan.
• HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah 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"
}

Konsol

Untuk menghapus resource API dengan UI:

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

   Buka hub API
2. Klik API.
3. Cari API dengan versi yang berisi spesifikasi yang ingin dihapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
4. Klik API untuk melihat detailnya.
5. Pada tab Versi, cari versi yang berisi spesifikasi yang ingin dihapus.
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 hub API, 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 hub API disediakan.
• HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
• API_ID: ID unik resource API.
• VERSION_ID: ID unik versi.
• SPEC_ID: ID unik spesifikasi yang akan dihapus.

Konsol

Anda dapat melakukan perubahan pada spesifikasi yang sudah ada melalui Konsol Google Cloud. Misalnya, Anda dapat mengubah nama tampilan, mengunggah file spesifikasi baru, mengubah jenis file, lalu edit atribut:

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

   Buka hub API
2. Klik API.
3. Cari API dengan versi yang berisi spesifikasi yang ingin Anda edit. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
4. Klik API untuk melihat detailnya.
5. Pada tab Versi, cari versi yang berisi spesifikasi yang ingin Anda edit.
6. Pilih versi.
7. Di halaman Versi, cari spesifikasi yang ingin Anda edit.
8. Pilih Edit dari menu Tindakan di baris spesifikasi yang ingin diedit.
9. Di panel pengeditan spesifikasi, Anda dapat mengubah spesifikasi berikut {i>metadata<i}:
   • Nama tampilan
   • Jenis file spesifikasi
   • Dokumen spesifikasi: Jelajahi file spesifikasi baru untuk 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 hub API disediakan.
• HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
• API_ID: ID unik resource API.
• VERSION_ID: ID unik versi.
• SPEC_ID: ID unik spesifikasi.
• Isi Permintaan: Gunakan isi permintaan untuk menentukan atribut yang akan diubah. Lihat Definisi resource spesifikasi.

Konsol

Untuk melihat detail spesifikasi menggunakan UI:

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

   Buka hub API
2. Klik API.
3. Cari API dengan versi yang berisi spesifikasi yang ingin dihapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
4. Klik API untuk melihat detailnya.
5. Pada tab Versi, cari versi yang berisi spesifikasi yang ingin Anda periksa.
6. Klik nama spesifikasi untuk melihat kontennya.

REST

API mengambil konten mentah berenkode Base64 dari spesifikasi API yang diupload ke hub API. Gunakan API Get spesifikasi 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 hub API disediakan.
• HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
• API_ID: ID unik resource API.
• VERSION_ID: ID unik versi.
• SPEC_ID: ID unik spesifikasi.

Contoh output:

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