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 mempermudah prosesnya, gunakan praktik terbaik berikut saat mengonfigurasi atau membuat API.

Membangun API baru

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

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

Hindari pembuatan metode kustom jika memungkinkan. 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 dari 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, berikut ini valid karena merujuk ke resource /foo yang sama:

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

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

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

Untuk 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.

Menggunakan penamaan yang konsisten di seluruh antarmuka

Buat 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 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 menyetel opsi API lanjutan.

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

Mengintegrasikan API yang sudah ada

Mengintegrasikan API yang ada dapat menjadi proses yang sangat bervariasi, bergantung pada API. Oleh karena itu, tidak ada serangkaian praktik terbaik konkret yang dapat diterapkan secara umum di semua API. Berikut adalah daftar saran umum yang dapat 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 dibuat server yang diperlukan oleh metode API, Anda harus menyiapkan pemetaan input untuk mendapatkan nilai yang dibuat server dan memetakannya untuk setiap permintaan.

Langkah berikutnya