With HAL Explorer you can explore HAL and HAL-FORMS based RESTful Hypermedia APIs.

© 2023 The original authors.

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Project Metadata

1. Introduction

1.1. Fundamentals

With HAL Explorer you can browse and explore HAL and HAL-FORMS-based RESTful Hypermedia APIs. HAL Explorer was inspired by Mike Kelly’s HAL-Browser. HAL Explorer also supports Spring Profiles. For further understanding of this document, please be aware of both

1.2. Features

  • Responsive design

  • Syntax highlighted response body

  • Custom request headers

  • Available Themes

  • 2 layouts

    • 2 column layout with optional documentation

    • 3 column layout with documentation always visible if available

  • API URL, theme, layout, and request headers stored as URL fragment

  • Support for Spring Data Rest profiles to populate properties in request editor

  • Support for HAL-FORMS templates

    • Template elements in response explorer (see screenshot)

    • Template properties in request editor

    • Options support in request editor

  • HAL-FORMS property constraint validation in request editor

2. Setup

2.1. Releases and Demos

Here you find the documentation for the latest release and the current snapshot, as well as the latest release and the current snapshot of HAL Explorer (both with examples):

Latest Release

1.2.2

HAL Explorer Demo

Current Snapshot

1.2.3-SNAPSHOT

HAL Explorer Demo

To explore your services with these HAL Explorer demos, they have to enable CORS. When you want to explore a Spring-based service (e.g. running on localhost), you could (temporarily) add a simple CORS Filter to your service. For more options, see section Development Server.

You can also play with the latest snapshot version of HAL Explorer.

2.2. Integration with your Backends

If you want to use a released version of HAL Explorer in a Java-based project, you could define a dependency to the HAL Explorer WebJar.

Maven
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>hal-explorer</artifactId>
    <version>1.2.0</version>
</dependency>
Gradle
implementation 'org.webjars:hal-explorer:1.2.0'

When you use the WebJar with Spring Boot, you can access the HAL Explorer in a Web browser at /webjars/hal-explorer/1.2.0/index.html.

If you are using Spring Data REST, you could instead add a dependency like

Maven
<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-rest-hal-explorer</artifactId>
</dependency>
Gradle
implementation 'org.springframework.data:spring-data-rest-hal-explorer'

When you use spring-data-rest-hal-explorer, you can access the HAL Explorer in a Web browser at /.

Of course, you could always download a zip-based distribution and put it on any Web server.

The easiest way to integrate the upstream version of HAL Explorer into your backend would be to clone this Git repo, do a production build (see below) and then copy the content of the dist folder to a location accessible by your backend server. When you use Spring Boot, a good location in your project’s source tree would be src/main/java/resources/static/hal-explorer.

2.3. Build

2.3.1. node.js

  • Install the latest version of node.js and yarn (npm i -g yarn).

  • Run yarn build to build the project in production mode.

  • The build artifacts will be stored in the dist/ directory.

2.3.2. Development Server

Run yarn start for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files. The development server has a build-in proxy configuration so that all calls to /api are forwarded to localhost:8080/api. This is convenient when you want to test a local server without having to deal with CORS. If you run yarn startl, an additional file server is started with port 3000. In the test-data directory, you find some JSON examples. Try it out with the URL http://localhost:4200/#uri=http://localhost:3000/movies.hal-forms.json.

2.3.3. Gradle/Java Build Support

If you have Java installed, you can also build the project with Gradle. The Gradle build will install Node.js locally in the project directory. Run ./gradlew build (or just gradlew build under Windows) to build the project in production mode. The build artifacts will be stored in the dist/ directory.

2.3.4. Building the docs

You can build this documentation

  • Windows: gradlew doc

    • If you see errors regarding file encoding, try gradlew doc -Dfile.encoding=UTF-8

  • Linux: ./gradlew doc

2.3.5. Running Tests

  • yarn test to run the unit test suite against your default browser.

  • yarn test-headless to run the unit test suite against headless Chrome.

  • yarn e2e to run the e2e test suite against your default browser.

  • yarn e2e-headless to run the e2e test suite against headless Chrome.

Take a look at package.json for more test options.

3. Using HAL Explorer

3.1. JSON Properties

When you start HAL Explorer, you see an input field in the top left area, where you can input the URI of a REST service, that returns HAL or HAL-FORMS documents. Once you click Go! or hit enter, the response is displayed. A typical response would look like

hal explorer

3.2. Links

Just below the URI you find the top-level JSON properties. If the response contains links, you find them below. Since HAL does not provide any affordances what HTTP method you should use to follow the link, you find colored buttons for each HTTP method:

  • < : HTTP GET

  • + : HTTP POST

  • > : HTTP PUT

  • > : HTTP PATCH

  • x : HTTP DELETE

If a link relation provides Curie-based Documentation, you can click on the book icon to display it.

If a link relation provides a name or a title, they are displayed in the links table.

You can click on a link button to follow the link. If a link is templated, a modal dialog will pop up, where you can fill the template parameters, like

templated request

When you click on Go!, an HTTP call to the Expanded URI will be made.

3.3. Embedded Resources

If the response contains embedded resources, you find them in the section "Embedded Resources". You can click on an embedded resource to expand it, like

expanded embedded resource

3.4. Response Details

On the right-hand side of the page you find details about the response:

  • The Response Status code and text

  • All Response Headers

  • The response body in highlighted JSON

3.5. Curie-based Documentation

Whenever you see a book icon, you can click on it, and the documentation is shown. Depending on the chosen layout, the documentation will be displayed as a third column on the right (3 column layout) or will replace the response details (2 column layout). You can change the layout using the Settings menu at the main toolbar.

A page with 3 column layout might look like

3 column layout

3.6. HAL-FORMS

HAL Explorer supports the latest HAL-FORMS specification. Whenever a HAL-FORMS based response contains templates (_templates), all template elements will be displayed under the Links section, like

hal explorer templates

Since HAL-FORMS uses affordances to describe which HTTP method should be used for each template element, you can only follow links using HTTP GET, but use exactly the HTTP method specified in a template element.

3.7. Updating REST Resources

Whenever you click on an HTTP POST button, a modal dialog pops up, where you can enter the body of the post, and the query parameters (only if the URI is templated). In raw HAL based documents, it looks like

hal post dialog

When your server is implemented using Spring Data REST, a JSON Schema-based Spring profile is automatically created. HAL Explorer automatically detects Spring Profiles, and instead of just presenting an empty body, form elements for all attributes are displayed, like

request input

When your response is based on HAL-FORMS, all the properties of the corresponding template element are shown, like

hal forms post dialog

When HAL-FORMS is used, the fields are also validated and validation errors are displayed below the input area. Only for valid forms, the body is displayed, and the HTTP request can be made.

3.8. Adding Request Headers

When want to add certain request headers to all calls, click on Edit Headers in the top-left corner. THen, a modal dialog pops up where you can add headers. This is handy when you want to add things like bearer tokens for authorization, like

request headers

The modal dialog also provides buttons to clear all request headers or to add/modify an Accept request header for HAL or HAL-FORMS documents.

3.9. Bookmarking

The following configuration is transported in HTTP parameters, so HAL Explorer URL can easily be bookmarked:

  • URI

  • Request Headers

  • Layout

  • Theme

3.10. HAL-FORMS Options

HAL Explorer supports HAL-FORMS Options. A simple example JSON looks like

{
  "_links": {
    "self": {
      "href": "http://localhost:3000/options.hal-forms.json"
    }
  },
  "_templates" : {
    "default" : {
      "title": "Shipping",
      "method": "POST",
      "properties" : [
        {
          "name" : "shipping",
          "prompt" : "Select Shipping Method",
          "options" : {
            "selectedValues" : ["FedEx"],
            "inline" : ["FedEx","UPS","DHL"],
            "maxItems": 1
          }
        }
      ]
    }
  }
}

When clicking on the POST request button, the dialog looks like

hal forms options

In the top-level menu you can choose the theme, a few settings, and a small about dialog.

4.1. Theming

HAL Explorer supports all the Bootswatch themes (by Thomas Park).

4.2. Settings

In the Settings sub menu, you can choose

  • the layout (see Curie-based Documentation).

    • Supported layouts are 2 Colum Layout and 3 Column Layout.

  • if HAL EXPLORER should automatically do an HTTP OPTIONS request to figure out which HTTP methods are supported for a given link URI.

  • if you want to enable all HTTP methods for links in an HAL-FORMS document.

    • Usually HAL-FORMS _templates would be used to specify affordances with explicit HTTP methods. But there are some use cases where you might want to be able to make calls using other HTTP methods than GET for certain links.

5. License

HAL Explorer is licensed under MIT, see http://toedter.mit-license.org