Best Praktis Merancang dan Membuat Api

Let’s create better API

Beberapa dari kita mungkin sudah pernah mendengar salah satu mandat atau wejangan dari CEO amazone Jeff Bezos terhadap para developer perusahaanya. Apabila belum, berikut adalah beberapa point yang perlu kita ketahui sebagai developer atau pembuat software.

1. Semua team akan mengkespose data atau funsional dari codenya melalui service interface.
2. Semua team dan service akan berkomunikasi melalui service interface yang telah di buat tadi.
3. Sudah tidak boleh melakukan komunikasi semisal pembacaan langsung dari data source team lain, tidak ada penggunaan model memory yang di gunakan bersama, dan tidak ada jalan belakang. Semua proses komunikasi harus di lakukan melalui service interface yang dipanggil melalui jaringan network.
4. Tidak peduli teknologi yang digunakan mau HTTP, Corba, Pubsub, atau Grpc yang terpenting komunikasi musti lewat service interface.
5. Semua service iterface tadi musti dirancang dari bottom to top agar dapat digunakan oleh team luar. Dengan kata lain semua team harus merencanakan bahwa service iterfacenya akan di gunakan oleh dunia luar.
6. Semua orang yang tidak melakukan hal-hal di atas akan dipecat. (Ngeri banget !!!!).

Pada akhirnya hal-hal di atas menjadi key penentu kesuksesan amazone sehingga menjadi Amazone seperti sekarang ini dan salah satu layanan cloud yang terkenalnya adalah AWS.

API End Point

Misalkan kita akan membuat beberapa api dari data company dan employee maka jangan gunakan bentuk api-api seperti berikut.

• /addNewEmployee
• /updateEmployee
• /deleteEmployee
• /deleteAllEmployees
• /promoteEmployee
• /promoteAllEmployees

Gunakanlah HTTP method (Get, Post, Put, Delete, dll) sehingga api kita menjadi seperti berikut.

1. Get dengan path /companies akan membarikan semua data perusahaan yang ada.
2. Get dengan path /companies/33 akan memberikan data detil dari perusahaan dengan id 33.
3. Get dengan path /companies/33/employees akan memberikan semua data employee dari perusahaan dengan id 33.
4. POST dengan path /companies/33/employees akan membuat data baru employe untuk perusahaan dengan id 33.
5. PUT dengan path /companies/33/employees akan melakuka update data employe pada perusahaan dengan id 33. Dan perlu di perhatikan bahwa methode put ini idempoten sehingga di hit beberapa kali juga akibatnya sama.

HTTP Code Sebagai Standard

Gunakanlah standarisasi dari HTTP code sebagai berikut.

1. 2xx sebagi sukses kategori.
2. 200 OK sebagai balikan sukses untuk POST, GET, dan PUT.
3. 201 created sebagai balikan POST.
4. 204 No Content sebagai balikan apabila kita berhasil melakukan method Delete.
5. 4xx sebagai balikan client error.
6. 401 Bad Request sebagai balikan jika input data tidak dikenali atau salah.

Untuk lebih detil mengenai http code ini bisa di lihat di sini.

Searching, Sorting, Filtering, dan Pagination

Semua aksi ini hanyalah pencarian pada satu dataset. Tidak akan ada set API baru untuk menangani keperluan ini. Kita hanya perlu menambahkan parameter pencarian dengan metode GET Api.

• Sorting, gunakan cara berikut, GET /companies?sort=rank_asc akan mengahasilkan data perusahaan yang sudah tersorting berdasarkan rank secara asncending.
• Filtering, gunakan cara berikut GET /companies?category=banking&location=eropa akan menghasilkan data data-data perusahaan dengan category banking dan lokasinya berada di eropa.
• Pagination, gunakan cara berikut, GET /companies?page=23 akan menghasilkan data dari perusahaan page ke 23.
• Apabila terlalu panjang parameter yang kita gunakan dan gabungkan biasanya menghasilkan 414 URI Too long HTTP status. Kalau kondisi ini terjadi maka pindahkanlah methode get ke method post.

Versioning

Gunakan versioning yang jelas sehingga perubahan yang terjadi tidak mengakibatkan terganggunya client yang menggunakan api-api kita. Gunakan seperti betikut, http://api.yourservice.com/v1/companies/34/employees.

Untuk perancangan Api yang lebih standar dan di fahami oleh semua, alangkah baiknya kita gunakan standarisai misalkan Open API specifications.

Pebahasan selanjutnya dari serial service komunikasi pada microservie akan kita fokuskan pada konsep service discovery, circuit braker, dan client side load balancing.