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
- Baca tentang persyaratan API untuk menambahkan API ke Deployment Manager
- Ikuti petunjuk untuk menambahkan API.
- Pelajari opsi API lanjutan lebih lanjut.
- Pelajari jenis lebih lanjut.
- Baca tentang membuat konfigurasi.
- Membuat deployment menggunakan penyedia jenis baru Anda