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

API memiliki dokumen deskripsi yang valid

Dokumen deskriptor menjelaskan API dan resource-nya. Deployment Manager hanya dapat diintegrasikan dengan API yang didukung oleh spesifikasi OpenAPI atau dokumen deskriptif Google Discovery. Untuk informasi komprehensif 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, pastikan untuk menghosting dokumen deskriptor Anda di tempat yang dapat diakses oleh Deployment Manager. 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

Saat ini Deployment Manager 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 berfungsi:

  • Membuat operasi - Membuat resource. Permintaan ini harus berupa permintaan HTTP POST.
  • Operasi baca - Mendapatkan informasi tentang resource API. Permintaan ini harus berupa permintaan HTTP GET.
  • Operasi update - Memperbarui resource. Permintaan ini harus berupa permintaan HTTP PUT
  • Operasi hapus - Menghapus resource. Permintaan 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 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 resource atau memperbarui resource setelah diakuisisi, tetapi resource tersebut tidak dapat dihapus.
Ya Tidak Tidak Ya Pengguna dapat menghapus resource dan mendapatkan resource, atau menambahkan resource yang sudah ada ke deployment.
Ya Tidak Tidak Tidak Pengguna dapat memperoleh resource yang sudah 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 terdapat di semua metode API, sehingga Deployment Manager dapat mencocokkan parameter tersebut saat pengguna menyediakannya. Kondisi berikut berlaku untuk parameter jalur dan kueri.

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

Hal berikut 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 bukan sebagai parameter jalur untuk metode lain. Dalam hal ini, kolom ini harus 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 pada resource, tetapi tidak ada saat membuat permintaan POST. Jika properti id diharuskan untuk membuat permintaan ke resource yang ada, tetapi properti tidak berada pada resource atau tersedia di jalur, hal ini akan menyebabkan gangguan dalam mentransfer API ke Deployment Manager.

Perilaku API pelan memerlukan konfigurasi tambahan

Ada perilaku API tertentu yang 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 dalam 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 suatu resource sebelum mengizinkan permintaan update. Gunakan Advanced API Options untuk memberi tahu Deployment Manager agar mendapatkan nilai ini setiap kali pengguna membuat permintaan untuk mengupdate deployment.

  • Memanipulasi input pengguna: Misalnya, jika API Anda memerlukan nilai kolom harus 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 menurut setiap metode: Untuk metode yang menggunakan kembali kolom yang sama, tetapi dengan nilai yang berbeda, Anda dapat menggunakan opsi API untuk menyatakan ke Deployment Manager kapan harus menggunakan nilai yang mana.

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

Langkah selanjutnya