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 persis sama dengan spesifikasi yang dijelaskan di sini, Anda mungkin dapat mengatasi inkonsistensi ini menggunakan Opsi API Lanjutan.

API memiliki dokumen deskriptor yang valid

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

Endpoint dokumen deskriptor API dapat diakses

Deployment Manager membuat permintaan HTTP untuk mendapatkan dokumen deskriptor API, jadi Anda harus memastikan untuk menghosting dokumen deskriptor di suatu 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 artikel 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:

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

API yang hanya mendukung operasi CRUD parsial 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 melepaskan resource, 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 menggunakan kebijakan ACQUIRE.
Ya Tidak Ya Tidak Pengguna dapat memperoleh 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 ada ke deployment.
Ya Tidak Tidak Tidak Pengguna dapat memperoleh resource yang ada atau menghapusnya dengan kebijakan ABANDON.

Semua parameter jalur dan kueri berhasil diselesaikan

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 dapat muncul sebagai parameter jalur untuk satu metode, tetapi tidak sebagai parameter jalur untuk metode lainnya. Dalam hal ini, kolom harus menjadi 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, diasumsikan bahwa 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 mentransfer API ke Deployment Manager.

Perilaku API yang tidak terlalu terlihat 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 Anda membuat permintaan untuk memperbarui deployment dengan nilai ini.

  • Memanipulasi input pengguna: Misalnya, jika API Anda mewajibkan nilai kolom selalu diawali dengan ID project, Anda dapat menggunakan pemetaan input untuk menambahkan informasi tersebut secara otomatis, alih-alih 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 yang mana.

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

Langkah berikutnya