Praktik Terbaik untuk Menambahkan Penyedia Jenis

Halaman ini menjelaskan praktik terbaik untuk membuat API baru yang akan ditambahkan ke Deployment Manager sebagai Penyedia Jenis atau menambahkan API yang ada sebagai penyedia jenis.

Deployment Manager memungkinkan Anda menambahkan API sebagai penyedia jenis untuk mengekspos resource API sebagai jenis yang dapat Anda panggil dalam konfigurasinya. Untuk memudahkan prosesnya, gunakan praktik terbaik ini saat mengonfigurasi atau membuat API.

Mem-build API baru

Jika Anda mem-build API baru yang ingin diintegrasikan dengan Deployment Manager, gunakan praktik terbaik ini.

Gunakan metode Create, Read, Update, and Delete (CRUD) standar dan hindari metode kustom

Hindari membuat metode kustom jika memungkinkan. Tetap gunakan metode REST standar seperti metode GET, POST, PUT, dan DELETE. Metode ini dikenali oleh Deployment Manager dan dapat dipetakan secara otomatis.

Untuk Discovery API, Anda harus memberi nama metode API sesuai dengan pemetaan berikut:

Metode REST Penamaan API yang direkomendasikan
POST create atau insert
GET get
PUT update
DELETE delete

Untuk spesifikasi OpenAPI, Anda tidak dapat memberi nama metode API secara berbeda dengan metode REST standar.

Menggunakan jalur resource yang dapat diprediksi

Untuk spesifikasi OpenAPI, Deployment Manager mendukung dua perilaku untuk mengidentifikasi antarmuka RESTful. Yang pertama adalah jika semua metode REST untuk resource berada di jalur resource yang sama:

/foo/{name}
  post:
  get:
  delete:
  put:

Jika Anda harus memisahkan metode, gunakan jalur resource yang sama. Misalnya, hal berikut valid karena merujuk ke resource /foo yang sama:

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

Namun, hal berikut tidak valid karena merujuk ke dua resource yang berbeda dari tampilan Deployment Manager:

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

Dalam kasus yang jarang terjadi, Anda mungkin tergoda untuk memberi nama jalur resource seperti ini:

foo/create
  post:

foo/delete
  delete:

Hal ini tidak valid dari tampilan Deployment Manager karena tidak dapat mengidentifikasi antarmuka RESTful.

Gunakan penamaan yang konsisten di seluruh antarmuka

Pastikan nama input dan jalur tetap sama antara metode POST dan PUT. Hal ini juga berlaku untuk nilai parameter. Artinya, pertahankan sintaksis untuk nilai parameter yang sama di seluruh metode.

Misalnya, jika Anda memiliki parameter bernama email untuk isi permintaan permintaan POST, jangan beri nama parameter yang sama emailAddress untuk permintaan PUT.

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

Jika Anda harus menambahkan jenis perilaku ini, beri tahu Deployment Manager cara menangani perilaku ini dengan menetapkan opsi API lanjutan.

Selain itu, pertahankan isi permintaan untuk metode POST dan PUT agar tetap sama. Untuk metode GET dan DELETE, hanya jalur yang berlaku karena tidak ada isi permintaan untuk metode ini.

Mengintegrasikan API yang ada

Mengintegrasikan API yang ada dapat menjadi proses yang sangat bervariasi, bergantung pada API. Dengan demikian, tidak ada kumpulan praktik terbaik konkret yang dapat diterapkan secara umum di semua API. Berikut adalah daftar saran umum yang mungkin membantu saat mempertimbangkan cara mengintegrasikan API yang ada.

  • Gunakan wrapper API untuk API non-RESTful.

    Jika API yang ada bukan RESTful API, Anda dapat membuat wrapper API untuk mengekspos metode REST saja.

  • Jika API hampir RESTful, identifikasi dan perbarui API.

    Jika API Anda hampir RESTful dan hanya memiliki beberapa perilaku non-REST, Anda dapat mengupdate API untuk menyelesaikan perilaku ini.

  • Nilai yang dihasilkan server selalu memerlukan pemetaan input.

    Jika API Anda memiliki nilai yang dihasilkan server yang diperlukan oleh metode API, Anda harus menyiapkan pemetaan input untuk mendapatkan nilai yang dihasilkan server dan memetakan untuk setiap permintaan.

Langkah selanjutnya