Persyaratan API untuk Mengintegrasikan API

Dokumen ini menjelaskan persyaratan umum API yang ingin Anda tambahkan sebagai penyedia jenis ke Deployment Manager. Gunakan panduan ini untuk memahami karakteristik API yang diharapkan Deployment Manager. Jika API Anda tidak sepenuhnya cocok dengan spesifikasi yang dijelaskan di sini, Anda mungkin dapat menyelesaikan inkonsistensi ini menggunakan Opsi API Lanjutan.

API memiliki dokumen deskripsi yang valid

Dokumen deskripsi menjelaskan API dan resource-nya. Hanya API yang didukung oleh spesifikasi OpenAPI atau dokumen deskripsi Google Discovery yang dapat diintegrasikan dengan Deployment Manager. Untuk mengetahui informasi lengkap tentang cara membuat spesifikasi OpenAPI, lihat repo GitHub OpenAPI.

Endpoint dokumen deskripsi API dapat diakses

Deployment Manager membuat permintaan HTTP untuk mendapatkan dokumen deskripsi API, jadi Anda harus memastikan untuk menghosting dokumen deskripsi di tempat yang dapat diakses oleh Deployment Manager. URL tersebut dapat berupa URL yang tersedia secara publik atau endpoint yang dilindungi oleh autentikasi dasar.

API menerima autentikasi dasar atau OAuth2 jika dihosting di layanan Google tertentu

Deployment Manager saat ini mendukung autentikasi dasar (nama pengguna dan sandi) serta autentikasi OAuth 2.0 untuk API tertentu yang dihosting di Google Kubernetes Engine atau di Google Endpoints. Anda dapat menyiapkan autentikasi untuk menggunakan akun layanan project.

Untuk mengetahui informasi selengkapnya, baca Membuat Penyedia Jenis.

Mendukung operasi Create, Read, Update, Delete (CRUD)

API yang dimaksud harus berupa API RESTful yang mendukung operasi CRUD. Artinya, ada metode yang melakukan:

  • Membuat operasi - Membuat resource. Ini harus berupa permintaan HTTP POST.
  • Operasi baca - Mendapatkan informasi tentang resource API. Ini harus berupa permintaan HTTP GET.
  • Operasi pembaruan - Memperbarui resource. Ini harus berupa permintaan HTTP PUT
  • Operasi hapus - Menghapus resource. Ini harus berupa permintaan HTTP DELETE.

API yang hanya mendukung operasi CRUD sebagian akan tetap berfungsi, tetapi perilakunya akan berbeda bergantung pada operasi yang tersedia.

Mendukung permintaan GET Mendukung permintaan CREATE Mendukung permintaan UPDATE Mendukung permintaan DELETE Perilaku API khusus?
Ya Ya Ya Ya Tidak ada.
Ya Ya Ya Tidak Pengguna dapat meninggalkan referensi, tetapi tidak dapat menghapusnya.
Ya Ya Tidak Ya Setiap perubahan pada resource yang ada akan gagal. Pengguna harus menghapus dan membuat ulang resource untuk memperbaruinya.
Ya Ya Tidak Tidak Kedua perilaku yang dijelaskan di atas.
Ya Tidak Ya Ya Jika API tidak mendukung permintaan pembuatan, pengguna dapat menambahkan resource yang ada ke deployment dengan memperbarui deployment dengan kebijakan ACQUIRE.
Ya Tidak Ya Tidak Pengguna dapat memperoleh resource atau memperbarui resource setelah diperoleh, tetapi resource tidak dapat dihapus.
Ya Tidak Tidak Ya Pengguna dapat menghapus resource dan mendapatkan resource, atau dapat menambahkan resource yang sudah ada ke deployment.
Ya Tidak Tidak Tidak Pengguna dapat memperoleh resource yang ada atau menghapusnya dengan kebijakan ABANDON.

Semua parameter jalur dan kueri berhasil di-resolve

Semua parameter jalur dan kueri API harus ada sebagai bagian dari isi resource atau ada di semua metode API, sehingga Deployment Manager dapat mencocokkan parameter saat pengguna menyediakannya. Kondisi berikut berlaku untuk parameter jalur dan kueri.

Setiap parameter jalur/kueri untuk POST harus berupa parameter untuk PUT

Berikut ini tidak valid karena myParameter ada untuk POST, tetapi tidak untuk PUT:

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

Setiap parameter untuk metode non-POST harus ada di semua antarmuka metode, atau sebagai bagian dari resource, dengan pertimbangan khusus jika parameter ini dihasilkan oleh server.

Dalam skenario kasus terbaik, API mungkin terlihat seperti ini, dengan parameter name muncul untuk semua metode.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

Dalam skenario lain, kolom mungkin muncul sebagai parameter jalur untuk metode, tetapi tidak sebagai parameter jalur untuk metode lain. Dalam hal ini, kolom harus merupakan bagian dari resource API. Contoh:

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

Dalam contoh ini, asumsinya adalah id adalah nilai yang dihasilkan server yang ada di resource, tetapi tidak ada saat membuat permintaan POST. Jika properti id diperlukan untuk membuat permintaan ke resource yang ada, tetapi properti tidak ada di resource atau tersedia di jalur, hal ini menyebabkan hambatan dalam melakukan porting API ke Deployment Manager.

Perilaku API yang halus memerlukan konfigurasi tambahan

Ada perilaku API tertentu yang akan memerlukan konfigurasi API tambahan untuk mengintegrasikan API dengan Deployment Manager. Perilaku ini mencakup:

  • Nilai yang dihasilkan server: Beberapa resource API memiliki properti yang dihasilkan server yang berubah setelah setiap permintaan atau saat peristiwa tertentu terjadi di API. Anda dapat menggunakan opsi API lanjutan untuk memberi tahu Deployment Manager agar mendapatkan nilai baru ini setiap kali permintaan dibuat.

    Misalnya, API mungkin memerlukan properti sidik jari terbaru dari resource sebelum mengizinkan permintaan update. Gunakan Opsi API Lanjutan untuk memberi tahu Deployment Manager agar mendapatkan nilai ini setiap kali pengguna membuat permintaan untuk mengupdate deployment dengan nilai ini.

  • Memanipulasi input pengguna: Misalnya, jika API Anda mewajibkan nilai kolom selalu diawali dengan project ID, Anda dapat menggunakan pemetaan input untuk menambahkan informasi tersebut secara otomatis, bukan memaksa pengguna untuk menambahkannya secara manual.

  • Nilai kolom yang berubah dengan setiap metode: Untuk metode yang menggunakan kembali kolom yang sama, tetapi dengan nilai yang berbeda, Anda dapat menggunakan opsi API untuk menyatakan kepada Deployment Manager kapan harus menggunakan nilai mana.

Untuk mengetahui informasi selengkapnya, baca artikel Menetapkan Opsi API Lanjutan.

Langkah selanjutnya