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.

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

Membuat API baru

Jika Anda membangun API baru yang ingin diintegrasikan dengan Deployment Manager, gunakan praktik terbaik berikut.

Menggunakan metode Create, Read, Update, dan Delete (CRUD) standar serta 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 boleh memberi nama metode API 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 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 berikut:

foo/create
  post:

foo/delete
  delete:

Nilai 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 di antara metode POST dan PUT. Hal ini juga berlaku untuk parameter value. Artinya, pastikan sintaksis untuk parameter value tetap 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, pastikan 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

Integrasi API yang sudah 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 ini daftar saran umum yang mungkin membantu saat mempertimbangkan cara untuk mengintegrasikan API yang sudah ada.

  • Menggunakan wrapper API untuk API non-RESTful.

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

  • Jika API hampir RESTful, identifikasi dan update API tersebut.

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

  • Nilai yang dihasilkan server selalu memerlukan pemetaan input.

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

Langkah selanjutnya