HAL Explorer allows you to explore HAL and HAL-FORMS based RESTful Hypermedia APIs.

© 2025 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

HAL Explorer allows you to browse and explore HAL and HAL-FORMS-based RESTful Hypermedia APIs. HAL Explorer was inspired by Mike Kelly’s HAL-Browser and also supports Spring Profiles. For a complete understanding of this documentation, please familiarize yourself with:

1.2. Features

  • Color Modes

    • Dark

    • Light

    • Auto (automatically detects system preference)

  • Available Themes

    • Bootstrap 5 default theme

    • Bootswatch themes (25+ themes available; Cosmo is the default)

  • Column Layouts

    • 2 column layout with optional documentation

    • 3 column layout with documentation always visible when available

  • Full HTTP Method Support

    • GET, POST, PUT, PATCH, DELETE operations

    • HTTP OPTIONS method to discover available request options for links

    • Support for both simple and templated URIs

  • Request Features

    • API URL and custom request headers stored as URL fragment for easy sharing

    • Custom request headers editor

    • URI template parameter editor with validation

    • Keyboard shortcuts (Enter to submit, ESC to close dialogs)

  • Settings

    • All settings stored in the browser’s local storage with hal-explorer. namespace

    • Configurable HTTP OPTIONS usage for link discovery

    • Option to enable all HTTP methods for HAL-FORMS links

    • Scrollable documentation mode for large documentation content

  • Spring Data REST Integration

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

    • Automatic content type detection

  • HAL-FORMS Support

    • Template elements displayed in response explorer (see screenshot)

    • Template properties in request editor

    • Options support with inline and linked values

    • Multiple selection support for array properties

    • Property constraint validation in request editor

  • Error Handling

    • Graceful handling of error responses (401, 404, etc.)

    • Display of HAL-FORMS documents even in error responses

    • Links and affordances remain accessible in error scenarios

  • Response Explorer

    • Syntax-highlighted JSON display

    • Expandable/collapsible sections for properties, links, embedded resources

    • Response status, headers, and body information

    • Documentation integration (when available)

2. Setup

2.1. Releases and Demos

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

Latest Release

1.2.3

HAL Explorer Demo

Current Snapshot

2.0.0-SNAPSHOT

HAL Explorer Demo

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

You can also experiment 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 can define a dependency to the HAL Explorer WebJar.

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

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

If you are using Spring Data REST, you can 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 HAL Explorer in a web browser at /.

You can also download a zip-based distribution and deploy it on any web server.

The easiest way to integrate the upstream version of HAL Explorer into your backend is to clone this Git repository, 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/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 built-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 start:fs, an additional file server is started on port 3000. In the test-data directory, you will 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 runs the unit test suite against your default browser.

  • yarn test:headless runs the unit test suite against headless Chrome.

  • yarn e2e runs the e2e test suite against default browsers (using Playwright).

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

3. Using HAL Explorer

3.1. JSON Properties

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

hal explorer light

3.2. Links

Just below the URI, you will find the top-level JSON properties. If the response contains links, they are displayed below. Since HAL does not provide affordances indicating which HTTP method you should use to follow a link, you will 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 appear where you can fill in 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 will find them in the "Embedded Resources" section. 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 will find details about the response:

  • Response Status code and text

  • All Response Headers

  • Response body with syntax-highlighted JSON

3.5. Curie-based Documentation

Whenever you see a book icon, you can click on it to display the documentation. 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 in the main toolbar.

A page with a 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 in 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 follow links using HTTP GET, but must use the specific HTTP method defined in each template element.

3.7. Updating REST Resources

Whenever you click on an HTTP POST button, a modal dialog appears where you can enter the request body and query parameters (only if the URI is templated). For 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 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 is the body displayed, and the HTTP request can be made.

3.8. Adding Request Headers

When you want to add certain request headers to all calls, click on Edit Headers in the top-left corner. Then, a modal dialog will appear where you can add headers. This is useful when you want to add items 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. Configuration and Bookmarking

The following configuration is stored in the browser’s local storage and persists across sessions:

  • Color Mode (Light/Dark/Auto; default is Auto)

  • Theme (default is Bootswatch Cosmo)

  • Column Layout (2 or 3 columns; default is 2)

  • HTTP OPTIONS setting (default is off)

  • Enable all HTTP Methods for HAL-FORMS Links setting (default is off)

  • Scrollable Documentation setting (default is off)

3.9.1. Bookmarking

The following configuration is included in URL parameters, so HAL Explorer URLs can be easily bookmarked and shared:

  • URI

  • Request Headers

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 color mode, theme, and settings, and view the About dialog.

4.1. Color Mode

HAL Explorer supports three color modes:

  • Light - Light color scheme

  • Dark - Dark color scheme

  • Auto - Automatically detects your system’s preferred color scheme (default)

The color mode is stored in your browser’s local storage and persists across sessions.

4.2. Theming

HAL Explorer supports all of the Bootswatch themes (by Thomas Park). The default theme is Cosmo. You can select from 25+ different themes, including:

  • Default (HAL Explorer’s default theme)

  • Cosmo, Darkly, Flatly, Materia, and many more

The selected theme is stored in your browser’s local storage and persists across sessions.

4.3. Settings

In the Settings submenu, you can configure:

  • Layout - Choose between different column layouts (see Curie-based Documentation)

    • 2 Column Layout - Two columns with optional documentation

    • 3 Column Layout - Three columns with documentation always visible when available

  • Use HTTP OPTIONS - Enable automatic HTTP OPTIONS requests to discover which HTTP methods are supported for a given link URI

  • Enable all HTTP Methods for HAL-FORMS Links - Enable all HTTP methods for links in HAL-FORMS documents

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

  • Scrollable Documentation - When enabled, documentation is rendered in a scrollable iframe with a fixed maximum height instead of expanding the main page height

All settings are stored in your browser’s local storage with the hal-explorer. prefix and persist across sessions.

4.4. About

The About dialog displays:

  • Author information

  • Version number

  • GitHub repository link

  • License information (MIT)

5. License

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