Penyemak Imbas Spring REST dan HAL

REST Teratas

Saya baru sahaja mengumumkan kursus Learn Spring yang baru , yang berfokus pada asas-asas Spring 5 dan Spring Boot 2:

>> SEMAK KURSUS

1. Gambaran keseluruhan

Dalam tutorial ini, kita akan membincangkan apa itu HAL dan mengapa ia berguna, sebelum memperkenalkan penyemak imbas HAL .

Kami kemudian akan menggunakan Spring untuk membina API REST sederhana dengan beberapa titik akhir yang menarik dan mengisi pangkalan data kami dengan beberapa data ujian.

Akhirnya, dengan menggunakan penyemak imbas HAL, kami akan meneroka API REST kami dan mengetahui cara melintasi data yang terdapat di dalamnya.

2. HAL dan Penyemak Imbas HAL

JSON Hypertext Application Language, atau HAL, adalah format sederhana yang memberikan cara yang konsisten dan mudah untuk membuat hyperlink antara sumber dalam API kami . Dengan memasukkan HAL dalam REST API kami menjadikannya lebih mudah diterangkan kepada pengguna dan juga pada dasarnya mendokumentasikan diri.

Ia berfungsi dengan mengembalikan data dalam format JSON yang menguraikan maklumat yang relevan mengenai API.

Yang berkisar model HAL sekitar dua konsep yang mudah.

Sumber, yang mengandungi:

  • Pautan ke URI yang berkaitan
  • Sumber Terbenam
  • Nyatakan

Pautan:

  • URI sasaran
  • Hubungan, atau rel, ke pautan
  • Beberapa sifat pilihan lain untuk membantu penyusutan, perundingan kandungan, dll

Penyemak imbas HAL dibuat oleh orang yang sama yang mengembangkan HAL dan menyediakan GUI dalam penyemak imbas untuk melintasi API REST anda .

Kami sekarang akan membina REST API yang mudah, pasangkan penyemak imbas HAL dan terokai ciri-cirinya.

3. Kebergantungan

Berikut adalah kebergantungan tunggal yang diperlukan untuk mengintegrasikan penyemak imbas HAL ke REST API kami. Anda boleh mencari selebihnya kebergantungan untuk API dalam kod GitHub.

Pertama, kebergantungan untuk projek berasaskan Maven:

 org.springframework.data spring-data-rest-hal-browser 3.2.6.RELEASE 

Sekiranya anda membina dengan Gradle, anda boleh menambahkan baris ini ke fail build.gradle anda :

compile group: 'org.springframework.data', name: 'spring-data-rest-hal-browser', version: '3.0.8.RELEASE'

4. Membina API REST Mudah

4.1. Model Data Ringkas

Dalam contoh kami, kami akan menyiapkan REST API yang mudah untuk melihat pelbagai buku di perpustakaan kami.

Di sini, kami menentukan entiti buku ringkas yang mengandungi anotasi yang sesuai sehingga kami dapat meneruskan data dengan Hibernate:

@Entity public class Book { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private long id; @NotNull @Column(columnDefinition = "VARCHAR", length = 100) private String title; @NotNull @Column(columnDefinition = "VARCHAR", length = 100) private String author; @Column(columnDefinition = "VARCHAR", length = 1000) private String blurb; private int pages; // usual getters, setters and constructors }

4.2. Memperkenalkan CRUD Repository

Seterusnya, kita memerlukan beberapa titik akhir. Untuk melakukan ini, kita dapat memanfaatkan PagingAndSortingRepository dan menentukan bahawa kita ingin mendapatkan data dari entiti Buku kita .

Kelas ini memberikan arahan CRUD yang mudah, serta keupayaan paging dan menyusun langsung dari kotak:

@Repository public interface BookRepository extends PagingAndSortingRepository { @RestResource(rel = "title-contains", path="title-contains") Page findByTitleContaining(@Param("query") String query, Pageable page); @RestResource(rel = "author-contains", path="author-contains", exported = false) Page findByAuthorContaining(@Param("query") String query, Pageable page); }

Sekiranya ini kelihatan agak pelik, atau jika anda ingin mengetahui lebih lanjut mengenai Spring Repositories, anda boleh membaca lebih lanjut di sini.

Kami telah memperluas repositori dengan menambahkan dua titik akhir baru:

  • findByTitleContaining - mengembalikan buku yang mengandungi pertanyaan yang termasuk dalam tajuk
  • findByAuthorContaining - mengembalikan buku dari pangkalan data di mana pengarang buku mengandungi pertanyaan

Perhatikan bahawa titik akhir kedua kami mengandungi atribut export = false . Atribut ini menghentikan pautan HAL yang dihasilkan untuk titik akhir ini , dan tidak akan tersedia melalui penyemak imbas HAL.

Akhirnya, kami akan memuatkan data kami ketika Spring dimulakan dengan menentukan kelas yang menerapkan antara muka ApplicationRunner . Anda boleh mendapatkan kod di GitHub.

5. Memasang Penyemak Imbas HAL

Penyediaan untuk penyemak imbas HAL sangat mudah ketika membuat REST API dengan Spring. Selagi kita memiliki ketergantungan, Spring akan mengkonfigurasi penyemak imbas secara automatik, dan menyediakannya melalui titik akhir lalai.

Yang perlu kita buat sekarang ialah tekan tekan dan beralih ke penyemak imbas. Penyemak imbas HAL kemudian akan tersedia di // localhost: 8080 /

6. Meneroka API REST Kami Dengan Penyemak Imbas HAL

The pelayar HAL dipecahkan kepada dua bahagian - explorer dan pemeriksa . Kami akan membahagikan dan meneroka setiap bahagian secara berasingan.

6.1. Penjelajah HAL

Kedengarannya, penjelajah dikhaskan untuk meneroka bahagian baru API kami berbanding dengan titik akhir semasa . Ini berisi bar pencarian, serta kotak teks untuk menampilkan Header Permintaan Kustom dan Properties dari titik akhir semasa.

Di bawah ini, kami mempunyai bahagian pautan dan senarai Sumber Terbenam yang boleh diklik.

6.2. Menggunakan Pautan

Sekiranya kita menavigasi ke titik akhir / buku kita dapat melihat pautan yang ada:

Ini link yang dijana daripada HAL dalam seksyen bersebelahan:

"_links": { "first": { "href": "//localhost:8080/books?page=0&size=20" }, "self": { "href": "//localhost:8080/books{?page,size,sort}", "templated": true }, "next": { "href": "//localhost:8080/books?page=1&size=20" }, "last": { "href": "//localhost:8080/books?page=4&size=20" }, "profile": { "href": "//localhost:8080/profile/books" }, "search": { "href": "//localhost:8080/books/search" } },

Sekiranya kita berpindah ke titik akhir carian, kita juga dapat melihat titik akhir khusus yang kita buat menggunakan PagingAndSortingRepository:

{ "_links": { "title-contains": { "href": "//localhost:8080/books/search/title-contains{?query,page,size,sort}", "templated": true }, "self": { "href": "//localhost:8080/books/search" } } } 

HAL di atas menunjukkan tajuk kami -mengandungi titik akhir yang menunjukkan kriteria carian yang sesuai. Perhatikan bagaimana titik akhir yang mengandungi pengarang hilang kerana kami menentukan bahawa tidak boleh dieksport.

6.3. Melihat Sumber Terbenam

Sumber Terbenam menunjukkan perincian rekod buku individu di titik akhir / buku kami . Setiap sumber juga mengandungi bahagian Properties dan Links sendiri :

6.4. Menggunakan Borang

Butang tanda tanya di lajur GET di bahagian pautan menunjukkan bahawa bentuk mod dapat digunakan untuk memasukkan kriteria carian tersuai.

Here is the form for our title-contains endpoint:

Our custom URI returns the first page of 20 books where the title contains the word ‘Java'.

6.5. The Hal Inspector

The inspector makes up the right side of the browser and contains the Response Headers and Response Body. This HAL data is used to render the Links and Embedded Resources that we saw earlier in the tutorial.

7. Conclusion

In this article, we've summarised what HAL is, why it's useful and why it can help us to create superior self-documenting REST APIs.

Kami telah membina REST API sederhana dengan Spring yang menerapkan PagingAndSortingRepository , dan juga menentukan titik akhir kami sendiri. Kami juga telah melihat bagaimana untuk mengecualikan titik akhir tertentu dari penyemak imbas HAL .

Setelah menentukan API kami, kami mengisi dengan data ujian dan menerokainya secara terperinci dengan bantuan penyemak imbas HAL. Kami melihat bagaimana penyemak imbas HAL disusun, dan UI mengawal yang membolehkan kami melalui API dan meneroka datanya.

Seperti biasa, kodnya tersedia di GitHub.

REST bawah

Saya baru sahaja mengumumkan kursus Learn Spring yang baru , yang berfokus pada asas-asas Spring 5 dan Spring Boot 2:

>> SEMAK KURSUS