Пролетен браузър REST и HAL

ПОЧИВКА Най-горе

Току що обявих новия курс Learn Spring , фокусиран върху основите на Spring 5 и Spring Boot 2:

>> ПРЕГЛЕД НА КУРСА

1. Общ преглед

В този урок ще обсъдим какво е HAL и защо е полезен, преди да представим браузъра HAL .

След това ще използваме Spring, за да изградим прост REST API с няколко интересни крайни точки и да попълним нашата база данни с някои тестови данни.

И накрая, използвайки браузъра HAL, ще проучим нашия REST API и ще открием как да прекосим данните, съдържащи се в него.

2. HAL и браузърът HAL

JSON Hypertext Application Language или HAL е прост формат, който дава последователен и лесен начин за хипервръзка между ресурси в нашия API . Включването на HAL в нашия REST API го прави много по-изследваем за потребителите, както и по същество самодокументиране.

Той работи чрез връщане на данни в JSON формат, който очертава съответната информация за API.

Моделът HAL се върти около две прости концепции.

Ресурси, които съдържат:

  • Връзки към съответните URI адреси
  • Вградени ресурси
  • Щат

Връзки:

  • Целеви URI
  • Връзка или rel към връзката
  • Няколко други незадължителни свойства за помощ при амортизация, договаряне на съдържание и т.н.

Браузърът HAL е създаден от същия човек, който е разработил HAL и предоставя GUI в браузъра, за да премине през вашия REST API .

Сега ще изградим прост REST API, ще включим HAL браузъра и ще проучим функциите.

3. Зависимости

По-долу е дадена единичната зависимост, необходима за интегриране на HAL браузъра в нашия REST API. Можете да намерите останалите зависимости за API в кода на GitHub.

Първо, зависимостта за проекти, базирани на Maven:

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

Ако изграждате с Gradle, можете да добавите този ред към вашия файл build.gradle :

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

4. Изграждане на опростен REST API

4.1. Прост модел на данни

В нашия пример ще настроим прост REST API за сърфиране в различни книги в нашата библиотека.

Тук дефинираме проста книга, която съдържа подходящи пояснения, за да можем да съхраняваме данните с хибернация:

@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. Представяме ви CRUD хранилище

След това ще ни трябват крайни точки. За целта можем да използваме PagingAndSortingRepository и да посочим, че искаме да получаваме данни от нашата книга .

Този клас предоставя прости CRUD команди, както и възможности за пейджинг и сортиране веднага:

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

Ако това изглежда малко странно или ако искате да научите повече за Spring Repositories, можете да прочетете повече тук.

Разширихме хранилището, като добавихме две нови крайни точки:

  • findByTitleContaining - връща книги, които съдържат заявката, включена в заглавието
  • findByAuthorContaining - връща книги от базата данни, където авторът на книга съдържа заявката

Имайте предвид, че втората ни крайна точка съдържа атрибут export = false . Този атрибут спира генерираните HAL връзки за тази крайна точка и няма да бъде достъпен чрез браузъра HAL.

И накрая, ще заредим данните си, когато Spring е стартиран, като дефинираме клас, който реализира интерфейса ApplicationRunner . Можете да намерите кода на GitHub.

5. Инсталиране на браузъра HAL

Настройката за браузъра HAL е изключително лесна при изграждането на REST API с Spring. Докато имаме зависимостта, Spring ще конфигурира автоматично браузъра и ще го направи достъпен чрез крайната точка по подразбиране.

Всичко, което трябва да направим сега, е да натиснем run и да преминем към браузъра. След това браузърът HAL ще бъде достъпен на // localhost: 8080 /

6. Проучване на нашия REST API с браузъра HAL

В браузъра HAL е разделена на две части - изследовател и на инспектора . Ще разделим и ще разгледаме всеки раздел поотделно.

6.1. HAL Explorer

Както звучи, изследователят се е посветил на изследването на нови части от нашия API спрямо текущата крайна точка . Той съдържа лента за търсене, както и текстови полета за показване на персонализирани заглавки на заявки и свойства на текущата крайна точка.

Под тях имаме раздела за връзки и списък с вградени ресурси за вграждане.

6.2. Използване на връзки

Ако отидем до крайната точка на нашата / книги, можем да видим съществуващите връзки:

Тези връзки се генерират от HAL в съседния раздел:

"_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.

Изградихме прост REST API с Spring, който реализира PagingAndSortingRepository , както и дефинира собствените ни крайни точки. Видяхме също как да изключим определени крайни точки от браузъра HAL .

След като дефинирахме нашия API, ние го попълнихме с тестови данни и го изследвахме подробно с помощта на браузъра HAL. Видяхме как е структуриран браузърът HAL и контролите на потребителския интерфейс, които ни позволиха да преминем през API и да проучим неговите данни.

Както винаги, кодът е достъпен в GitHub.

ПОЧИВКА отдолу

Току що обявих новия курс Learn Spring , фокусиран върху основите на Spring 5 и Spring Boot 2:

>> ПРЕГЛЕД НА КУРСА