Spring REST dan HAL Browser

REST Top

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

>> LIHAT KURSUSnya

1. Ikhtisar

Dalam tutorial ini, kita akan membahas apa itu HAL dan mengapa itu berguna, sebelum memperkenalkan browser HAL .

Kami kemudian akan menggunakan Spring untuk membangun REST API sederhana dengan beberapa titik akhir yang menarik dan mengisi database kami dengan beberapa data pengujian.

Terakhir, menggunakan browser HAL, kita akan menjelajahi REST API dan menemukan cara melintasi data yang ada di dalamnya.

2. HAL dan Browser HAL

JSON Hypertext Application Language, atau HAL, adalah format sederhana yang memberikan cara yang konsisten dan mudah untuk membuat hyperlink antar resource di API kami . Menyertakan HAL dalam REST API kami membuatnya lebih mudah dieksplorasi oleh pengguna serta pada dasarnya mendokumentasikan diri sendiri.

Ia bekerja dengan mengembalikan data dalam format JSON yang menguraikan informasi yang relevan tentang API.

Model HAL berkisar pada dua konsep sederhana.

Sumber daya, yang berisi:

  • Tautan ke URI yang relevan
  • Sumber Daya Tersemat
  • Negara

Tautan:

  • URI target
  • Relasi, atau rel, ke tautan
  • Beberapa properti opsional lainnya untuk membantu depresiasi, negosiasi konten, dll

Browser HAL dibuat oleh orang yang sama yang mengembangkan HAL dan menyediakan GUI dalam browser untuk melintasi REST API Anda .

Kami sekarang akan membangun REST API sederhana, pasang browser HAL dan jelajahi fitur-fiturnya.

3. Ketergantungan

Di bawah ini adalah ketergantungan tunggal yang diperlukan untuk mengintegrasikan browser HAL ke REST API kami. Anda dapat menemukan dependensi lainnya untuk API di kode GitHub.

Pertama, ketergantungan untuk proyek berbasis Maven:

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

Jika Anda membangun dengan Gradle, Anda dapat menambahkan baris ini ke file build.gradle Anda :

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

4. Membangun REST API Sederhana

4.1. Model Data Sederhana

Dalam contoh kami, kami akan menyiapkan REST API sederhana untuk menjelajahi berbagai buku di perpustakaan kami.

Di sini, kami mendefinisikan entitas buku sederhana yang berisi penjelasan yang sesuai sehingga kami dapat menyimpan 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

Selanjutnya, kita membutuhkan beberapa titik akhir. Untuk melakukan ini, kita dapat memanfaatkan PagingAndSortingRepository dan menentukan bahwa kita ingin mendapatkan data dari entitas Book kita .

Kelas ini menyediakan perintah CRUD sederhana, serta kemampuan paging dan penyortiran langsung dari kotaknya:

@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); }

Jika ini terlihat agak aneh, atau jika Anda ingin tahu lebih banyak tentang Spring Repositories, Anda dapat membaca selengkapnya di sini.

Kami telah memperluas repositori dengan menambahkan dua titik akhir baru:

  • findByTitleContaining - mengembalikan buku yang berisi kueri yang disertakan dalam judul
  • findByAuthorContaining - mengembalikan buku dari database tempat penulis buku berisi kueri

Perhatikan bahwa titik akhir kedua kita berisi atribut export = false . Atribut ini menghentikan pembuatan tautan HAL untuk titik akhir ini , dan tidak akan tersedia melalui browser HAL.

Terakhir, kami akan memuat data kami saat Spring dimulai dengan menentukan kelas yang mengimplementasikan antarmuka ApplicationRunner . Anda dapat menemukan kode tersebut di GitHub.

5. Menginstal Browser HAL

Pengaturan untuk browser HAL sangat mudah saat membuat REST API dengan Spring. Selama kami memiliki ketergantungan, Spring akan mengonfigurasi browser secara otomatis, dan membuatnya tersedia melalui titik akhir default.

Yang perlu kita lakukan sekarang adalah menekan run dan beralih ke browser. Browser HAL kemudian akan tersedia di // localhost: 8080 /

6. Menjelajahi REST API Kami Dengan Browser HAL

The HAL browser dipecah menjadi dua bagian - explorer dan inspektur . Kami akan memecah dan menjelajahi setiap bagian secara terpisah.

6.1. Penjelajah HAL

Kedengarannya, penjelajah dikhususkan untuk menjelajahi bagian baru dari API kami relatif terhadap titik akhir saat ini . Ini berisi bilah pencarian, serta kotak teks untuk menampilkan Header Permintaan Kustom dan Properti dari titik akhir saat ini.

Di bawah ini, kami memiliki bagian tautan dan daftar Sumber Daya Tersemat yang dapat diklik.

6.2. Menggunakan Tautan

Jika kita menavigasi ke titik akhir / books kita dapat melihat tautan yang ada:

Ini link yang dihasilkan dari HAL di bagian yang berdekatan:

"_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" } },

If we move to the search endpoint, we can also view the custom endpoints we created using the PagingAndSortingRepository:

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

The HAL above shows our title-contains endpoint displaying suitable search criteria. Note how the author-contains endpoint is missing since we defined that it should not be exported.

6.3. Viewing Embedded Resources

Embedded Resources show the details of the individual book records on our /books endpoint. Each resource also contains its own Properties and Links section:

6.4. Using Forms

The question mark button in the GET column within the links section denotes that a form modal can be used to enter custom search criteria.

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 membangun REST API sederhana dengan Spring yang mengimplementasikan PagingAndSortingRepository , serta menentukan titik akhir kami sendiri. Kami juga telah melihat bagaimana mengecualikan titik akhir tertentu dari browser HAL .

Setelah mendefinisikan API kami, kami mengisinya dengan data uji dan menjelajahinya secara detail dengan bantuan browser HAL. Kami melihat bagaimana struktur browser HAL, dan kontrol UI yang memungkinkan kami untuk menelusuri API dan menjelajahi datanya.

Seperti biasa, kode tersedia di GitHub.

REST bawah

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

>> LIHAT KURSUSnya