HAL Explorer

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

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

Version control: https://github.com/toedter/hal-explorer
Bugtracker: https://github.com/toedter/hal-explorer/issues

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:

the HAL Specification
the HAL-FORMS Specification

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

2.1.0

HAL Explorer Demo

Current Snapshot

2.1.1-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>2.1.0</version>
</dependency>

Gradle

runtimeOnly 'org.webjars:hal-explorer:2.1.0'

When you use the WebJar with Spring Boot, you can access HAL Explorer in a web browser at /webjars/hal-explorer/2.1.0/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

runtimeOnly '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:

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:

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:

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.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:

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:

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:

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

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:

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:

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 provides a rich theming experience with support of the Bootstrap default theme and 26 Bootswatch themes (by Thomas Park). The default theme is Cosmo, which offers a clean, modern look that works well with both light and dark color modes.

You can select from 27 professionally designed themes to customize the look and feel of HAL Explorer:

Bootstrap Default - Bootstrap’s base theme
Brite - High contrast, colorful theme
Cerulean - Calm blue theme
Cosmo - Modern, flat design with blue accents (HAL Explorer default theme)
Cyborg - Dark theme with slate gray
Darkly - Dark theme with subdued colors
Flatly - Flat design with green accents
Journal - Newspaper-inspired crisp theme
Litera - Clean, readable typography
Lumen - Light theme with soft shadows
Lux - Elegant with gold accents
Materia - Material Design inspired
Minty - Fresh minty theme
Morph - Modern with gradients
Pulse - Purple-themed design
Quartz - Dark professional theme
Sandstone - Flat design with orange accents
Simplex - Minimalist white theme
Sketchy - Hand-drawn style
Slate - Dark theme with blue highlights
Solar - Dark theme with yellow highlights
Spacelab - Modern flat blue theme
Superhero - Dark comic book style
United - Ubuntu-inspired design
Vapor - Retro synthwave theme
Yeti - Clean, snowy white theme
Zephyr - Light, airy design

Here is an example of HAL Explorer using the Dark Cosmo theme:

The selected theme is stored in your browser’s local storage with the hal-explorer.theme key and persists across sessions. Themes automatically adapt to your selected color mode (light/dark/auto) for an optimal viewing experience.

4.3. Settings

The Settings submenu allows you to customize HAL Explorer’s behavior and user interface. All settings are automatically saved to your browser’s local storage with the hal-explorer. prefix and persist across sessions.

4.3.1. Layout

Choose between different column layouts to optimize your workspace (see Curie-based Documentation for more details):

2 Column Layout - Default layout with two columns
- Documentation panel appears only when explicitly toggled
- Provides more horizontal space for the main content
- Ideal for smaller screens or when documentation is not frequently needed
3 Column Layout - Expanded layout with three columns
- Documentation is always visible when available
- Provides a comprehensive overview of resources, actions, and documentation simultaneously
- Best for larger screens and documentation-heavy APIs

4.3.2. Use HTTP OPTIONS

When enabled, HAL Explorer automatically sends HTTP OPTIONS requests to discover which HTTP methods are supported for a given link URI.

This feature helps you understand the available operations without having to consult external API documentation. The supported methods are then displayed as available actions for that resource.

Default: Disabled

4.3.3. Enable all HTTP Methods for HAL-FORMS Links

When enabled, all HTTP methods (GET, POST, PUT, PATCH, DELETE, etc.) are available for links in HAL-FORMS documents, even if no explicit template is defined for that method.

Typically, HAL-FORMS _templates explicitly specify affordances with their corresponding HTTP methods. However, this setting is useful when:

You need to test different HTTP methods on the same endpoint
Your API supports additional methods not documented in the HAL-FORMS template
You want to explore API capabilities beyond the standard template definitions