Geekly articles weekly

Rekomendasi API REST - Contoh Desain Layanan Web di Jawa dan Musim Semi

Di artikel terakhir dalam seri ini, Anda akan belajar tentang rekomendasi REST API dan contoh pengembangan dari Java dan Spring Web Services.

Saat mengembangkan API REST yang baik, penting untuk memiliki layanan microser yang baik.
Bagaimana Anda mengembangkan API REST Anda? Apa praktik terbaik?


Anda akan belajar:


  • Bagaimana cara mengembangkan REST API yang baik?
  • Apa yang harus saya pikirkan ketika mengembangkan REST API?
  • Apa praktik terbaik untuk mengembangkan layanan web RESTful?

API SISA


Ini adalah artikel terakhir dari serangkaian artikel tentang REST API:


Gunakan Pendekatan Konsumen Pertama


Siapa yang akan menggunakan layanan Anda? Layanan konsumen.

Apakah Anda melihat layanan dari perspektif konsumen?

  • Jika Anda mengembangkan API, dapatkah konsumen Anda memahami API Anda?
  • Jika Anda menerbitkan sumber daya Anda, dapatkah konsumen menemukan dan mengaksesnya?
  • Bisakah konsumen memahami URI Anda?
  • Jenis layanan apa yang Anda sediakan?
  • Apakah ini aplikasi seluler atau aplikasi web?
  • Konsumen apa yang Anda harapkan, dan dapatkah konsumen jenis ini berubah di masa depan?
  • Jika Anda menerapkan sesuatu seperti HATEOAS, pikirkan tentang bagaimana pelanggan Anda akan menggunakannya sebelum menerapkannya.

  • Yang paling penting adalah memiliki dokumentasi yang bagus
  • Mempermudah pelanggan Anda untuk menghemat waktu Anda.
  • Semakin banyak konsumen dapat melakukannya sendiri, semakin sedikit pekerjaan untuk Anda.


Setiap kali Anda melakukan diskusi atau tinjauan layanan, taruh persyaratan pelanggan di tempat pertama.

Gunakan Pendekatan Kontrak Pertama


Apa itu kontrak?

Pembuat layanan web dianggap sebagai penyedia layanan . Aplikasi yang menggunakan layanan web adalah konsumen layanan . Kontrak adalah perjanjian antara penyedia dan konsumen tentang suatu layanan.



Untuk menggunakan layanan dengan benar, konsumen layanan harus sepenuhnya memahami kontrak. Kontrak mencakup perincian banyak aspek layanan, seperti:

  • Bagaimana cara memanggil layanan web?
  • Jenis transportasi apa yang digunakan?
  • Apa struktur permintaan dan responsnya?

Ini juga disebut definisi layanan .

Dalam pendekatan kontrak pertama, Anda terlebih dahulu menentukan kontrak layanan, dan kemudian hanya mengimplementasikan layanan.

Kontrak Pertama dengan WSDL


Misalnya, ketika Anda mendefinisikan layanan web SOAP, Anda menggunakan WSDL untuk menentukan kontrak.



WSDL menentukan apa titik akhir layanan, operasi yang Anda terbitkan, dan struktur permintaan dan respons.

Kontrak Dulu dengan Swagger / Open API


Saat Anda menggunakan layanan web RESTful, Swagger adalah alat yang populer untuk mendokumentasikan layanan web Anda.



Swagger memungkinkan Anda untuk menentukan sumber daya apa yang Anda berikan sebagai bagian dari API Anda. Ini mencakup detail setiap operasi, misalnya, apakah menggunakan XML, JSON, atau keduanya. Garis jawaban juga ada di sana.



Ini juga memberikan informasi terperinci tentang kode respons yang didukungnya. Anda juga dapat melihat bahwa sumber daya khusus ini, / jpa / pengguna :



mendukung operasi GET. Bahkan, itu juga mendukung operasi POST:



Skema respons, jika sumber ini tersedia, akan menjadi:



Definisi objek Pengguna ada dalam perjanjian Swagger sebagai:



Ini termasuk atribut: birthDate , id , nama , dan array pesan posting. Beberapa bidang juga menyertakan bidang deskripsi di dalamnya.

Dalam pendekatan kontrak pertama, sebelum mengimplementasikan layanan, Anda secara manual atau menggunakan aplikasi membuat definisi yang dibuat oleh Swagger.

Manfaat dari Pendekatan Pertama Kontrak


Menggunakan pendekatan kontrak pertama, Anda memikirkan pelanggan Anda dan bagaimana mereka dapat menggunakan layanan ini. Anda awalnya tidak khawatir tentang detail implementasi.

Jika pada tahap awal Anda sangat mementingkan implementasi, detail teknis menembus definisi layanan Anda.

Anda perlu memastikan bahwa definisi layanan Anda tidak bergantung pada platform yang Anda gunakan, baik itu Java, .NET atau lainnya.

Tetapkan Standar Organisasi untuk API REST


Pedoman penting untuk standar organisasi Anda adalah YARAS.



YARAS adalah singkatan dari Yet Another RESTful API Standard . YARAS memberikan standar, pedoman, dan konvensi yang harus diikuti ketika mengembangkan layanan web RESTful. Dia memberikan rekomendasi untuk hal-hal berikut:

  • Apa yang harus Anda beri nama layanan Anda
  • Bagaimana Anda harus menyusun permintaan dan tanggapan Anda
  • Bagaimana Anda harus menerapkan pemfilteran, penyortiran, pagination, dan tindakan lainnya
  • Bagaimana Anda harus mendekati versi
  • Bagaimana Anda perlu mendekati dokumentasi API

Pendekatan Terpadu untuk Pengembangan Layanan


Anda perlu menyelesaikan banyak masalah kompleks sebelum mulai merancang layanan web RESTful. Semua hal di atas, Anda perlu mencari tahu.

Kepemimpinan organisasi Anda tidak akan ingin tim yang berurusan dengan sumber daya yang berbeda memiliki pendekatan yang berbeda untuk hal-hal ini.

Misalnya, Tim-A tidak diinginkan untuk mengatur versi berdasarkan parameter kueri, dan Tim-B menggunakan versi berdasarkan URI.

Oleh karena itu, penting bahwa Anda memiliki standar organisasi yang jelas untuk pendekatan Anda terhadap layanan web RESTful.

Kustomisasi YARAS DI BAWAH kebutuhan organisasi


Hal yang baik tentang YARAS adalah dapat disesuaikan untuk memenuhi kebutuhan spesifik organisasi. Misalnya, Anda dapat:

  • Konfigurasikan seperti apa bentuk badan permintaan dan respons.
  • Pilih sistem kontrol versi tertentu

Karena YARAS memiliki cakupan yang cukup komprehensif, Anda dapat yakin bahwa Anda tidak melewatkan satu pun keputusan penting.

Memilih kerangka kerja standar perusahaan Kerangka kerja REST API


Kerangka kerja yang umum digunakan untuk membuat layanan web RESTful di dunia Java adalah Spring MVC, Spring REST, dan JAX-RS.

Jika Anda membuat aplikasi kerangka kerja / pola dasar / referensi khusus organisasi yang mematuhi standar organisasi umum di atas platform REST API pilihan Anda, ini akan memungkinkan tim untuk dengan mudah mematuhi standar umum.

Fitur khas meliputi:

  • Struktur Permintaan dan Tanggapan
  • Menangani kesalahan
  • penyaringan
  • Cari
  • Versi
  • Dukungan Jawaban Salah
  • Hateoas

Kerangka kerja standar menyediakan pendekatan terpadu untuk merancang dan mengimplementasikan layanan di seluruh organisasi.

Manajemen REST API Terdesentralisasi


Buat grup ahli dari tim yang membuat API REST dan bentuk tim manajemen. Tim bertanggung jawab atas

  • Meningkatkan Standar REST API
  • Membangun / Merancang Kerangka API REST Anda

Penggunaan HTTP secara luas


Setiap kali Anda memikirkan layanan web RESTful, pikirkan HTTP.

HTTP memiliki semua fitur yang membantu Anda membuat layanan web yang hebat.

Gunakan metode permintaan HTTP yang benar


Pikirkan tentang metode permintaan HTTP yang perlu Anda gunakan. Ketika Anda berpikir tentang mengimplementasikan suatu operasi, tentukan sumber daya yang harus dilakukan, dan kemudian temukan metode permintaan HTTP yang sesuai. Apakah Anda mengambil detail, membuat sesuatu, memperbarui sesuatu yang ada, atau menghapus yang sudah ada?

Menggunakan metode HTTP:

  • DAPATKAN
  • POST untuk membuat
  • PUT untuk memperbarui
  • HAPUS untuk menghapus
  • PATCH untuk pembaruan sebagian

Gunakan status respons HTTP yang sesuai


Saat melakukan operasi, pastikan Anda mengembalikan status respons yang benar.

Misalnya, ketika sumber daya tertentu tidak ditemukan, jangan melempar pengecualian server. Alih-alih, kirim kode respons yang sesuai dalam pesan respons, seperti 404 .

Jika benar-benar ada pengecualian server, kirim kembali kode 500 .

Jika validasi gagal, kirim kode untuk permintaan yang tidak valid.

Fokus pada kinerja


Setiap sumber daya dapat memiliki beberapa representasi - dalam format XML atau JSON. Konsumen layanan dapat memilih presentasi pilihan mereka.

Layanan mengembalikan 3 pengguna ketika kami mengirim permintaan GET. Dalam hal ini, kami mendapatkan representasi JSON dari sumber daya / pengguna .



Ketika konsumen tidak menunjukkan tampilan yang disukai, kami menggunakan JSON.



Konsumen dapat mengirim tajuk Terima untuk menunjukkan tampilan.



Badan respons sekarang memiliki konten XML:



Gunakan bentuk jamak


Selalu gunakan jamak ketika Anda menyebutkan sumber daya.

Mari kita lihat contoh sederhana. Misalkan kita memiliki layanan yang menampung sumber daya pengguna. Berikut ini menjelaskan cara mengaksesnya:

  • Buat pengguna: POST / pengguna
  • Hapus pengguna: HAPUS / pengguna / 1
  • Dapatkan semua pengguna: GET / pengguna
  • Dapatkan satu pengguna: GET / pengguna / 1

Preferensi beberapa pengguna daripada pengguna membuat URI lebih mudah dibaca.

  • Misalnya, jika kita menggunakan / pengguna alih-alih / pengguna untuk mendapatkan, GET / pengguna tidak meneruskan pesan yang benar kepada pembaca.

Buat dokumentasi yang bagus


Konsumen perlu memahami cara memanfaatkan layanan dengan sebaik-baiknya, dan cara terbaik untuk membantu mereka adalah membuat dokumentasi yang baik.

Layanan web SOAP dapat menggunakan fungsi WSDL, sementara layanan web RESTful memiliki opsi Swagger (sekarang standar dokumentasi Open API).

Memilih format hanya satu bagian dari pembuatan dokumentasi yang baik. Yang juga penting adalah penyediaan jumlah informasi yang tepat untuk membantu konsumen.

Dokumentasi harus lengkap dan mencakup hal-hal berikut:

  • Apa itu struktur permintaan dan respons?
  • Bagaimana seharusnya seorang konsumen mengotentikasi dirinya sendiri?
  • Apa batasan penggunaannya?
  • Tunjukkan semua jenis pesan respons dan kode status terkait yang dapat diharapkan dari layanan.

Buat portal dokumentasi REST API yang umum


Akan sangat membantu jika memiliki portal dokumentasi REST API yang umum untuk seluruh organisasi. Lihatlah satu portal seperti itu:



Portal semacam itu menyatukan semua sumber daya yang tersedia di organisasi. Memiliki antarmuka pengguna seperti UI Swagger akan memiliki manfaat tambahan. Dengan menggunakan Swagger UI, Anda dapat melihat dokumentasi dengan lebih detail:



Ini dapat digunakan bahkan oleh pengguna non-teknis. Informasi yang disediakan di sini meliputi:

  • Format Respon yang Diharapkan
  • Jenis konten
  • Kode Jawaban yang Didukung

Format dokumentasi dengan gaya permintaan / tanggapan langsung mungkin juga menarik.

Dukungan versi


Kontrol versi memerlukan kompleksitas luar biasa untuk layanan web. Mempertahankan beberapa versi berbeda dari layanan web yang sama sangat sulit. Cobalah untuk menghindari hal ini jika memungkinkan.

Namun, dalam skenario tertentu, kontrol versi tidak dapat dihindari.

Mari kita mulai dengan melihat contoh layanan. Misalkan kita awalnya mendefinisikan layanan yang memiliki kelas PersonV1 sebagai berikut:

Versi kelas ini tidak memperhitungkan bahwa nama dapat memiliki banyak sub-bagian, seperti nama depan dan belakang. Lihat ini:

Versi kedua dari kelas sumber telah diperbarui untuk memperbaiki anomali ini:

Kami tidak dapat segera mentransfer seluruh layanan untuk menggunakan PersonV2 ! Mungkin ada konsumen lain yang sedang menunggu tanggapan dalam format PersonV1 .

Di sinilah kontrol versi diperlukan.

Sekarang mari kita lihat opsi yang kita miliki untuk kontrol versi dari kedua sumber ini.

Menggunakan URI yang berbeda


Kami memiliki satu opsi - untuk menggunakan URI yang berbeda untuk sumber daya yang berbeda ini. Dalam kode ujian di bawah ini, kami menggunakan URI v1 / orang dan v2 / orang untuk membedakannya:

Jika Anda menjalankan permintaan GET untuk sumber daya v1 / orang :



Anda akan menerima informasi yang terkait dengan v1 . Untuk sumber lain:



Menggunakan parameter kueri


Metode kontrol versi kedua menggunakan parameter kueri:

Di URI / orang / param , jika kami mengirim parameter dengan versi = 1 , kami mengembalikan sumber daya tipe PersonV1 :



Untuk URI yang sama, parameter dengan versi = 2 mengembalikan sumber daya tipe PersonV2 :



Metode ini disebut versi menggunakan parameter kueri.

Menggunakan Header (Header)


Cara lain yang dapat Anda lakukan adalah kontrol versi dengan menentukan judul. Di sini kita menggunakan header yang disebut X-API-VERSION dan tandai URI sebagai / orang / header . Ketika nilai header adalah 1 , sumber daya tipe PersonV1 dikembalikan :



Ketika nilainya 2 , sumber daya tipe PersonV2 diambil:



Kami menggunakan atribut di header permintaan untuk melakukan kontrol versi untuk kami.

Menggunakan Terima Header


Metode terakhir untuk membuat versi menggunakan Header Terima. Jika konsumen menyertakan informasi versi pertama dalam Header Terima dari permintaan GET, sumber daya berikut dikembalikan:



Jika tidak, sumber daya tipe PersonV2 dikembalikan :



Metode kontrol versi ini disebut Accept Header Versioning atau Media Type Versioning , karena tipe MIME biasanya merupakan isi dari header Terima.

Perbandingan Metode Kontrol Versi


Sejauh ini, kami telah melihat empat jenis metode dalam versi:

  • Menggunakan URI yang berbeda
  • Menggunakan parameter kueri
  • Penggunaan header
  • Menggunakan Terima Header / Jenis Media

Yang mana yang terbaik? Yang benar adalah bahwa tidak ada jawaban tunggal untuk pertanyaan ini. Faktanya adalah bahwa raksasa Internet yang berbeda mendukung jenis-jenis versi yang berbeda.

  • Menggunakan berbagai URI - Twitter
  • Menggunakan Parameter Kueri - Amazon
  • Menggunakan Header - Microsoft
  • Menggunakan Accept Header / Media Type - GitHub


Anda perlu mengevaluasi keempat opsi ini sesuai dengan kebutuhan spesifik Anda. Ada sejumlah faktor penting untuk dipertimbangkan:

  • Polusi URI : Dengan mengontrol versi menggunakan URI dan parameter kueri, kami akhirnya mencemari ruang URI. Ini karena kami menambahkan awalan dan sufiks ke string utama URI. Kontrol versi menggunakan header menghindari ini.
  • Penyalahgunaan Judul HTTP . Dalam hal kontrol versi menggunakan tajuk dan Jenis Media, tajuk HTTP disalahgunakan karena tadinya tidak dimaksudkan untuk kontrol versi.
  • Caching : Sumber daya diidentifikasi oleh URI-nya. Namun, jika Anda tidak menggunakan URI untuk menentukan versinya, tetapi menggunakan mekanisme berbasis header, informasi versi tidak bisa di-cache. Jika caching HTTP penting bagi Anda, gunakan kontrol versi berdasarkan URI atau parameter permintaan.
  • Eksekusi Permintaan Browser : Versi berdasarkan judul dan jenis media memerlukan alat seperti tukang pos. Namun, jika konsumen layanan tidak mengerti secara teknis, lebih baik menggunakan kontrol versi berdasarkan parameter URI atau kueri.
  • Dokumentasi API : Anda juga perlu memikirkan bagaimana Anda ingin mendokumentasikan API Anda. Versi berdasarkan URI dan parameter kueri lebih mudah untuk didokumentasikan daripada dua jenis kontrol versi lainnya.

Pahami bahwa tidak ada solusi ideal tunggal!

Pikirkan tentang penanganan kesalahan


Ketika seorang konsumen mengajukan permintaan ke suatu layanan, penting bagi mereka untuk menerima jawaban yang benar. Setiap kali terjadi kesalahan, penting untuk mengirim respons yang sesuai.

Ketika seorang konsumen meminta sumber daya yang tidak ada


Jika kami mengirim permintaan GET untuk mencari pengguna yang ada, kami mendapat respons berikut:



Jika Anda mencari pengguna yang tidak ada:



Yang Anda dapatkan adalah 404 Tidak Ditemukan status. Ini adalah penanganan kesalahan yang baik karena menentukan dengan benar bahwa sumber daya tidak ditemukan dan tidak mengembalikan kesalahan server.

Sekarang mari kita mengirim permintaan GET ke URI yang tidak ada:



Seperti yang Anda lihat, Anda mendapatkan 404 status respons Tidak Ditemukan . URL yang tidak valid menunjukkan sumber daya yang tidak ada.

Status respons penting


  • 200 - sukses
  • 404 - sumber daya tidak ditemukan
  • 400 - permintaan tidak valid (misalnya, kesalahan validasi)
  • 201 - dibuat
  • 401 - tidak sah (jika otentikasi gagal)
  • 500 - kesalahan server

Rincian Kesalahan di Badan Respons


Ini membantu jika Anda memiliki struktur pengecualian standar ketika mengembangkan layanan Anda.



Untuk kesalahan spesifik, struktur respons spesifik dapat dikembalikan ke konsumen, dan ini mungkin menjadi standar di seluruh organisasi. Pastikan respons kesalahan juga dapat dibaca oleh konsumen, tanpa kebingungan.

Menggunakan Swagger atau Open API Documentation


Swagger menyediakan salah satu format dokumentasi paling populer untuk layanan web RESTful. Hari ini didukung oleh berbagai organisasi dan digunakan dalam sejumlah besar layanan. Di sini kita melihat dua aspek utama dari kesombongan:

  • Format Dokumentasi Swagger
  • Swagger UI, yang memungkinkan Anda untuk melihat dokumentasi Swagger dengan cara yang nyaman secara visual

Dokumentasi Swagger


Lihatlah JSON Swagger berikut ini:



Di tingkat atas, ini terlihat sangat mirip dengan definisi WSDL. Ini memiliki beberapa atribut penting:
  • host : di mana layanan ini berada
  • basePath : jalur tempat layanan berada
  • mengkonsumsi : permintaan apa yang diterima



  • menghasilkan : Apa jenis respons yang dihasilkan



  • jalur : berbagai sumber daya yang tersedia Dalam hal ini, Anda memiliki beberapa jenis sumber daya dalam daftar:



Ketika Anda melihat dokumentasi Swagger, Anda dapat dengan cepat mengidentifikasi sumber daya yang tersedia, operasi yang didukung, dan operasi yang terkait dengan setiap sumber daya:



Sumber daya / pengguna mendukung operasi GET dan POST . Untuk GET, Anda dapat melihat jenis respons dan permintaan yang didukung. Anda juga melihat berbagai jenis jawaban:



Perhatikan bahwa untuk jawaban 200, sirkuit juga disebut sebagai susunan Pengguna . Pengguna adalah bagian dari bagian definisi di bagian bawah dokumen:



Swagger sepenuhnya independen dari teknologi yang Anda gunakan untuk mengimplementasikan layanan web RESTful. Oh, semuanya berbasis JSON.

Memperkenalkan UI Sombong


UI Swagger adalah antarmuka pengguna yang hebat yang sangat berguna untuk memvisualisasikan dokumentasi Swagger untuk layanan web RESTful.Lihatlah screenshot di bawah ini:



Harap perhatikan bahwa kami telah memilih versi spesifik dari layanan web untuk melihat dokumentasinya. Berikut ini layar yang sama secara lebih terperinci:



Ketika kami membuka beranda, layar menjelaskan sumber daya yang tercantum:



Anda juga dapat melihat rangkaian operasi yang didukung untuk URL sumber daya:



Ketika Anda mengklik pada operasi GET dari sumber daya tertentu, Anda mendapatkan detailnya:



Anda dapat melihat bahwa skema Model digambarkan secara visual. Atribut birthDate , id , tautan , nama , dan pos juga ditampilkan. Anda juga dapat menjalankan kueri contoh dan melihat respons:



Menggunakan Swagger Tools (Open API Standard)


Hal terbaik dari Swagger adalah banyaknya alat yang tersedia di sekitarnya. Lihatlah layanan berikut yang kami gunakan sebelumnya untuk menjelaskan kontrol versi: Berikut adalah dokumentasi yang dibuat secara otomatis untuk layanan ini:



Swagger memiliki dukungan untuk pendekatan kontrak-pertama dan pendekatan kode-pertama.

Pada masalah ini ada video penulis .

Ringkasan


Pada artikel ini, kami melihat praktik terbaik untuk membuat dan merancang layanan web RESTful.

Bacaan tambahan


Jadilah yang TERBAIK di API SISA Anda!

Mengembangkan API REST

Source: https://habr.com/ru/post/id483374/

More articles:


All Articles