[[tools]]
= Tools

[[tools.hal-explorer]]
== The HAL Explorer

Kai Tödter has created a useful application: HAL Explorer (https://github.com/toedter/hal-explorer[Git Repo], https://toedter.github.io/hal-explorer/release/reference-doc/[Reference Doc], https://toedter.github.io/hal-explorer/release/hal-explorer/#theme=Cosmo&uri=examples/examples.hal-forms.json[Demo]). It is an Angular based web application that lets you easily explore HAL and HAL-FORMS based HTTP responses. It also supports Spring profiles generated by Spring Data REST. You can point it at any Spring Data REST API and use it to navigate the app and create new resources.

Instead of pulling down the files, embedding them in your application, and crafting a Spring MVC controller to serve them up, all you need to do is add a single dependency.

The following listing shows how to add the dependency in Maven:

====
[source,xml]
----
<dependencies>
  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-rest-hal-explorer</artifactId>
  </dependency>
</dependencies>
----
====

The following listing shows how to add the dependency in Gradle:

====
[source,groovy]
----
dependencies {
    implementation 'org.springframework.data:spring-data-rest-hal-explorer'
}
----
====

NOTE: If you use Spring Boot or the Spring Data BOM (bill of materials), you do not need to specify the version.

This dependency auto-configures the HAL Explorer to be served up when you visit your application's root URI in a browser. (NOTE: http://localhost:8080/api was plugged into the browser, and it redirected to the URL shown in the following image.)

image::hal-explorer-1.png[]

The preceding screenshot shows the root path of the API. On the right side are details from the response, including headers, and the body (a HAL document).

The HAL Explorer reads the links from the response and puts them in a list on the left side. You can either click on the green *GET* button and navigate to one of the collections, or click on the other buttons to make changes (POST, PUT, PATCH) or delete resources.

The HAL Explorer understands *URI Templates*. Whenever a link contains a URI template, a modal dialog pops up where you can enter the template parameters.

image::hal-explorer-3.png[]

If you click *Go!* without entering anything, the variables are essentially ignored. For situations like xref:projections-excerpts.adoc[Projections and Excerpts] or xref:paging-and-sorting.adoc[Paging and Sorting], this can be useful.

When you click on a *NON-GET* button with a `+` or a `>` sign on it, a modal dialog appears. It shows the HTTP method belonging to the clicked button. You can fill the body and submit the new JSON document.

Below the URI and HTTP method are the fields. These are automatically supplied, depending on the metadata of the resources, which was automatically generated by Spring Data REST. If you update your domain objects, the pop-up reflects it, as the following image shows:

image::hal-explorer-2.png[]
