HAL Explorer

HAL Explorer helps you 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. What is HAL Explorer?

HAL Explorer is a web-based tool for browsing and exploring RESTful Hypermedia APIs that use the HAL (Hypertext Application Language) and HAL-FORMS specifications. It provides an intuitive interface for developers and API consumers to navigate hypermedia-driven APIs, discover available resources, and interact with them using various HTTP methods.

1.2. Why Use HAL Explorer?

Traditional API exploration tools focus on endpoint documentation and testing. HAL Explorer takes a different approach by embracing the hypermedia-driven nature of REST APIs:

Self-Discovery: Navigate APIs by following links, just as intended by REST and HATEOAS principles
Visual Exploration: See the structure of your API responses with syntax highlighting and collapsible sections
Built-in Documentation: View inline documentation through CURIE links without leaving the interface
Developer-Friendly: Test POST, PUT, PATCH, and DELETE operations with guided form inputs
Framework Support: First-class support for Spring Data REST profiles and HAL-FORMS affordances

1.3. Fundamentals

HAL Explorer was inspired by Mike Kelly’s HAL-Browser and extends it with modern features including dark mode, multiple themes, HAL-FORMS support, and Spring Data REST integration.

1.3.1. Prerequisites

To get the most out of HAL Explorer and this documentation, you should be familiar with:

REST API Concepts: Basic understanding of HTTP methods, status codes, and RESTful design
HAL Specification: The HAL standard for representing resources with links and embedded resources
HAL-FORMS Specification: The HAL-FORMS extension for describing affordances and form templates
JSON Format: Basic knowledge of JSON syntax and structure

1.3.2. Supported Media Types

HAL Explorer can consume and display the following media types:

application/hal+json - Standard HAL format
application/prs.hal-forms+json - HAL-FORMS format with affordances
application/json - Plain JSON (limited functionality)

1.4. Features Overview

HAL Explorer provides a comprehensive set of features for exploring and interacting with HAL and HAL-FORMS APIs.

1.4.1. User Interface

Theming and Appearance

Color Modes
- Dark Mode - Optimized for low-light environments
- Light Mode - Traditional bright interface
- Auto Mode - Automatically detects and adapts to system preference (default)
Customizable Themes
- Bootstrap 5 default theme
- 26+ professionally designed Bootswatch themes
- Cosmo theme is the default (clean, modern flat design)
- All themes adapt to your selected color mode

Layout Options

2 Column Layout (Default)
- Resource explorer on the left
- Response details on the right
- Documentation panel toggles on demand
- Ideal for smaller screens or focused work
3 Column Layout
- Resource explorer on the left
- Response details in the middle
- Documentation always visible on the right
- Best for larger screens and documentation-heavy APIs

1.4.2. API Interaction

HTTP Method Support

Full REST Method Support
- GET - Retrieve resources
- POST - Create new resources
- PUT - Replace existing resources
- PATCH - Partially update resources
- DELETE - Remove resources
- OPTIONS - Discover available operations (optional, configurable)
URI Handling
- Simple URIs - Direct resource access
- Templated URIs - Interactive parameter editor with validation
- Automatic template parameter detection

Request Customization

Custom Headers
- Add authorization tokens (Bearer, Basic Auth, etc.)
- Set custom Accept headers for HAL or HAL-FORMS
- Configure any HTTP header needed by your API
- Headers stored in URL fragment for sharing
Request Editor
- Form-based input for HAL-FORMS and Spring profiles
- Real-time validation with error messages
- Query parameter support for templated URIs
Keyboard Shortcuts
- Enter - Submit requests
- ESC - Close dialogs
- Streamlined workflow for rapid exploration

1.4.3. Advanced Features

Spring Data REST Integration

HAL Explorer provides first-class support for Spring Data REST APIs:

Automatic detection of Spring Data REST profiles
JSON Schema-based property discovery
Auto-populated form fields based on entity definitions
Content-type negotiation and detection

HAL-FORMS Support

Full implementation of the HAL-FORMS specification:

Template elements displayed inline with links
Property definitions with type information
Options support (inline values and external links)
Multiple selection for array properties
Comprehensive validation (required fields, regex patterns, min/max values)
Prompt text and placeholder support

Documentation Integration

CURIE-based Documentation
- Click book icons to view inline documentation
- Documentation appears in dedicated panel with fixed-height scrollable iframe
- No need to leave the interface or consult external docs

Error Handling

Graceful handling of HTTP error responses (4xx, 5xx)
HAL-FORMS documents displayed even in error scenarios
Links and affordances remain accessible for recovery
Clear display of error status codes and messages

1.4.4. Data Management

Browser Storage

All settings and preferences persist across sessions:

Color mode preference
Selected theme
Column layout choice
HTTP OPTIONS setting
HAL-FORMS method enablement

Storage uses the hal-explorer. namespace to avoid conflicts.

Bookmarking and Sharing

Configuration embedded in URLs for easy sharing:

Current API URI
Custom request headers
Share exact API state with colleagues
Bookmark frequently accessed endpoints

1.4.5. Response Exploration

Syntax-Highlighted Display
- Color-coded JSON for easy reading
- Expandable/collapsible sections
- Navigate complex nested structures
Organized Sections
- Properties - Top-level resource attributes
- Links - Available hypermedia links with affordances
- Embedded Resources - Nested resources with full link support
- Templates - HAL-FORMS affordances (when available)
Response Metadata
- HTTP status code and status text
- All response headers
- Full response body
- Response timing information

2. Setup and Installation

This section covers different ways to use HAL Explorer, from quick online demos to full integration with your backend services.

2.1. Quick Start: Online Demos

The fastest way to try HAL Explorer is through our hosted demos:

Version	Number	Demo	Documentation
Latest Release	2.2.1	HAL Explorer Demo	Reference Docs
Current Snapshot	2.2.2-SNAPSHOT	HAL Explorer Demo	Reference Docs

Version

Number

Demo

Documentation

Latest Release

2.2.1

HAL Explorer Demo

Reference Docs

Current Snapshot

2.2.2-SNAPSHOT

HAL Explorer Demo

Reference Docs

You can also access the latest release at hal-explorer.com.

2.1.1. Using Online Demos with Your API

To explore your own API using a hosted HAL Explorer, your service must enable CORS (Cross-Origin Resource Sharing).

Quick CORS Setup for Spring Boot:

Add this simple CORS Filter to your Spring application:

@Component
public class CorsFilter implements Filter {
    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        HttpServletResponse response = (HttpServletResponse) res;
        response.setHeader("Access-Control-Allow-Origin", "*");
        response.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, PATCH, OPTIONS");
        response.setHeader("Access-Control-Allow-Headers", "*");
        chain.doFilter(req, res);
    }
}

This CORS configuration allows access from any origin. Use it only for development and testing. For production, restrict the Access-Control-Allow-Origin to specific domains.

For alternative approaches without CORS, see the Development Server section below.

2.2. Backend Integration

HAL Explorer can be integrated into your application in several ways, depending on your technology stack and deployment preferences.

2.2.1. Option 1: WebJar (Java Projects)

The simplest way to integrate HAL Explorer into a Java-based project is using the WebJar dependency.

Add the Dependency:

Maven

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>hal-explorer</artifactId>
    <version>2.2.1</version>
</dependency>

Gradle (Groovy)

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

Gradle (Kotlin)

runtimeOnly("org.webjars:hal-explorer:2.2.1")

Access HAL Explorer:

Once the dependency is added, HAL Explorer is available at:

http://localhost:8080/webjars/hal-explorer/2.2.1/index.html

You can create a redirect or custom controller to serve HAL Explorer at a more convenient path like /explorer or /api/explorer.

Example Spring Boot Controller:

@Controller
public class ExplorerController {
    @GetMapping("/explorer")
    public String explorer() {
        return "redirect:/webjars/hal-explorer/2.2.1/index.html";
    }
}

2.2.2. Option 2: Spring Data REST Integration

If you’re using Spring Data REST, there’s a dedicated integration package that makes HAL Explorer the default UI for your API root.

Add the Dependency:

Maven

<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-rest-hal-explorer</artifactId>
</dependency>

Gradle (Groovy)

runtimeOnly 'org.springframework.data:spring-data-rest-hal-explorer'

Gradle (Kotlin)

runtimeOnly("org.springframework.data:spring-data-rest-hal-explorer")

Access HAL Explorer:

With Spring Data REST integration, HAL Explorer is automatically available at your application root:

http://localhost:8080/

The integration automatically configures HAL Explorer to point to your Spring Data REST API.

2.2.3. Option 3: Static Distribution

For non-Java backends or custom deployment scenarios, you can use the standalone distribution.

Download and Extract:

Download the distribution ZIP file (v2.2.1)
Extract the contents to your web server’s static file directory

Example Deployment Locations:

Nginx: /usr/share/nginx/html/hal-explorer/
Apache: /var/www/html/hal-explorer/
Express.js: public/hal-explorer/
Spring Boot: src/main/resources/static/hal-explorer/

Configure Your Web Server:

For single-page application routing, configure your web server to serve index.html for all routes under the HAL Explorer path.

Example Nginx Configuration:

location /hal-explorer/ {
    alias /usr/share/nginx/html/hal-explorer/;
    try_files $uri $uri/ /hal-explorer/index.html;
}

2.2.4. Option 4: Build from Source

For the latest features or custom modifications, build HAL Explorer from source.

Steps:

Clone the repository:

git clone https://github.com/toedter/hal-explorer.git
cd hal-explorer

Build the project (see Build section below)
Copy the dist/hal-explorer/browser directory contents to your backend’s static file location

Recommended Spring Boot Location:

src/main/resources/static/hal-explorer/

This makes HAL Explorer available at http://localhost:8080/hal-explorer/.

3. Using HAL Explorer

This chapter guides you through common workflows and features in HAL Explorer.

3.1. Getting Started

3.1.1. Your First Request

When you open HAL Explorer, you’ll see a simple interface with a URI input field at the top:

Enter a URI: Type or paste the URL of your HAL or HAL-FORMS API endpoint
Click Go! or press Enter: HAL Explorer will fetch and display the response
Explore the Response: Navigate through properties, links, and embedded resources

Try the built-in examples first: Demo with Example Data

In the top-level toolbar, you can choose the color mode, theme, and settings, and view the About dialog.

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

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

3.2.3. Settings

The Settings menu helps 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.

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

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

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

Default: Disabled

Note: Use this setting with caution, as it may allow operations that the API doesn’t actually support.

3.2.4. About

The About dialog displays:

Author information
Version number
GitHub repository link
License information (MIT)

3.2.5. Understanding the Interface

The HAL Explorer interface is divided into main sections:

Top Bar
- URI input field and Go! button
- Edit Headers button for custom HTTP headers
- Color mode, theme, and settings menu
Left Panel (Main Content)
- Top-level JSON properties
- Links section with HTTP method buttons
- Embedded resources (expandable)
- Templates section (for HAL-FORMS)
Right Panel
- Response status and headers
- Syntax-highlighted response body
- Documentation panel (in 3-column mode or when toggled)

3.3. Working with Properties

When a response is displayed, top-level JSON properties appear at the top of the left panel.

Example Response:

{
  "id": 1,
  "title": "The Matrix",
  "year": 1999,
  "director": "Wachowski Sisters"
}

These properties are displayed in a clean, readable format with syntax highlighting.

3.4. Navigating Links

Links are the heart of hypermedia APIs. HAL Explorer makes it easy to discover and follow links in your API.

3.4.1. Link Display

Links appear in a dedicated section below the properties. Each link relation shows:

Relation name - The link relation type (e.g., self, items, next)
Name/Title - Optional descriptive text (if provided by the API)
HTTP method buttons - Actions you can perform on the link
Documentation icon - Book icon (if CURIE documentation is available)

3.4.2. HTTP Method Buttons

Since HAL doesn’t specify which HTTP methods are valid for each link, HAL Explorer provides buttons for all standard methods:

Button HTTP Method Typical Use

Button	HTTP Method	Typical Use
`<`	GET	Retrieve a resource
`+`	POST	Create a new resource or perform an action
`>>`	PUT	Replace an existing resource completely
`>`	PATCH	Partially update an existing resource
`x`	DELETE	Remove a resource

<

GET

Retrieve a resource

+

POST

Create a new resource or perform an action

>>

PUT

Replace an existing resource completely

>

PATCH

Partially update an existing resource

x

DELETE

Remove a resource

Enable the "Use HTTP OPTIONS" setting (see Settings) to automatically discover which methods are actually supported for each link.

3.4.3. Following Simple Links

To follow a link:

Click the appropriate HTTP method button (usually < for GET)
HAL Explorer fetches the linked resource
The new response appears in the interface

Example Workflow:

Start at API root: GET http://api.example.com/
See a link to "customers" collection
Click < (GET) button on the customers link
View the list of customers
Click < (GET) on a specific customer link
View individual customer details

3.4.4. Working with Templated Links

Some links include URI templates with parameters. When you click a method button for a templated link, HAL Explorer opens a dialog to collect parameter values.

Templated Link Example:

{
  "_links": {
    "search": {
      "href": "/customers{?name,city}",
      "templated": true
    }
  }
}

Using the Template Dialog:

Click the HTTP method button for the templated link
Enter values for each template parameter:
- name: "Smith"
- city: "Portland"
Review the expanded URI: /customers?name=Smith&city=Portland
Click Go! to execute the request

Features:

Validation: Required parameters are marked
Preview: See the expanded URI before sending
Keyboard Shortcut: Press Enter to submit, ESC to cancel

3.4.5. Link Names and Titles

APIs can provide additional context for links through name or title attributes:

{
  "_links": {
    "author": [
      {"href": "/users/1", "title": "John Smith"},
      {"href": "/users/2", "title": "Jane Doe"}
    ]
  }
}

HAL Explorer displays these in the links table, making it easy to choose the right link when multiple links share the same relation.

3.5. Exploring Embedded Resources

HAL allows resources to embed related resources directly in the response, reducing the need for additional HTTP requests.

3.5.1. What Are Embedded Resources?

Embedded resources appear in the _embedded section of a HAL response:

{
  "total": 2,
  "_embedded": {
    "customers": [
      {
        "id": 1,
        "name": "John Smith",
        "_links": {
          "self": {"href": "/customers/1"}
        }
      },
      {
        "id": 2,
        "name": "Jane Doe",
        "_links": {
          "self": {"href": "/customers/2"}
        }
      }
    ]
  }
}

3.5.2. Viewing Embedded Resources

HAL Explorer displays embedded resources in an expandable section:

Look for the "Embedded Resources" section
Click on an embedded resource relation to expand it
View the full resource details, including its own links and properties

3.5.3. Navigating Embedded Resources

Each embedded resource is fully interactive:

Follow links - Click HTTP method buttons on embedded resource links
Expand nested embeds - If an embedded resource contains its own embedded resources
View properties - See all attributes of the embedded resource

Example Workflow:

Fetch customer list: GET /customers
Expand embedded customers collection
View individual customer details inline
Click < (GET) on a customer’s self link to view full details
Follow orders link from customer to see their orders

This reduces navigation time while maintaining full API exploration capabilities.

3.6. Inspecting Response Details

The right panel provides comprehensive information about each API response.

3.6.1. Response Status

At the top of the right panel, you’ll see:

HTTP Status Code - e.g., 200, 201, 404, 500
Status Text - e.g., "OK", "Created", "Not Found", "Internal Server Error"
Status Color - Green for success (2xx), yellow for redirects (3xx), red for errors (4xx, 5xx)

3.6.2. Response Headers

All HTTP response headers are displayed in a collapsible section:

Common Headers:

Content-Type - Media type of the response (e.g., application/hal+json)
Content-Length - Size of the response body
Cache-Control - Caching directives
ETag - Version identifier for the resource
Last-Modified - When the resource was last changed

These headers are useful for:

Debugging caching issues
Understanding content negotiation
Implementing optimistic concurrency control
Analyzing API behavior

3.6.3. Response Body

The complete JSON response appears with:

Syntax Highlighting - Different colors for keys, values, strings, numbers
Collapsible Sections - Expand/collapse nested objects and arrays
Raw JSON - Exact server response, formatted for readability

Uses:

Compare left panel (structured view) with right panel (raw JSON)
Copy/paste JSON for testing or documentation
Inspect complex nested structures
Debug unexpected API responses

3.7. 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.8. 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.9. 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.10. Customizing Request Headers

Custom HTTP headers allow you to authenticate with your API, control content negotiation, and configure other request behaviors.

3.10.1. Opening the Headers Editor

Click the Edit Headers button in the top-left corner to open the request headers dialog.

3.10.2. Adding Custom Headers

Step-by-Step:

Click Edit Headers
Enter header name (e.g., Authorization)
Enter header value (e.g., Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…)
Click Add or press Enter
Click Done to close the dialog

All subsequent requests will include these headers.

3.10.3. Common Use Cases

Authentication

Bearer Token (JWT):

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Basic Authentication:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

API Key:

X-API-Key: your-api-key-here

Content Negotiation

Request HAL format:

Accept: application/hal+json

Request HAL-FORMS format:

Accept: application/prs.hal-forms+json

The headers dialog includes quick buttons to set these Accept headers.

Custom Headers

Add any custom headers required by your API:

X-Tenant-ID: tenant-123
X-Request-ID: abc-def-ghi
X-Correlation-ID: correlation-xyz

3.10.4. Managing Headers

View All Headers - All configured headers are listed in the dialog
Remove Headers - Click the delete icon next to any header
Clear All - Use the "Clear All" button to remove all custom headers
Persistence - Headers are stored in the URL fragment for bookmarking

Be careful sharing URLs that contain sensitive headers like authorization tokens. The headers are visible in the URL fragment.

3.11. 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)

3.11.1. Bookmarking

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

URI
Request Headers

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

4. Development Setup

This section covers building HAL Explorer from source, running the development server, and testing.

4.1. Prerequisites

Required:

Node.js: Version 18.x or higher (Download)
Yarn: Package manager (npm install -g yarn)

Optional (for Gradle build):

Java: JDK 17 or higher
Gradle: Included via Gradle Wrapper

4.2. Building for Production

4.3. Using Node.js/Yarn

This is the recommended build method for most users.

Steps:

# Install dependencies
yarn install

# Build for production
yarn build

The build artifacts will be stored in the dist/ directory, optimized and minified for production deployment.

Build Output:

dist/hal-explorer/ - Complete application ready for deployment
Minified JavaScript and CSS
Optimized assets and images
Generated source maps (for debugging)

4.4. Using Gradle

If you prefer using Gradle or don’t have Node.js installed globally, use the Gradle wrapper.

Steps:

# Unix/Linux/macOS
./gradlew build

# Windows
gradlew.bat build

The Gradle build automatically:

Downloads and installs Node.js locally in the project directory
Installs dependencies via Yarn
Runs the production build
Stores artifacts in the dist/ directory

This approach is useful for CI/CD pipelines and Java-centric development environments.

4.5. Development Server

4.6. Basic Development Server

Start the development server with hot reload:

yarn start

Features:

URL: http://localhost:4200/
Hot Reload: Automatically reloads when source files change
Source Maps: Full debugging support
Proxy Configuration: Built-in proxy to avoid CORS issues

Proxy Rules:

The development server automatically proxies certain paths:

/api/ → http://localhost:8080/api/ - Your backend API
/docs/ → http://localhost:8080/docs/ - API documentation

This allows you to develop against a local backend without CORS configuration.

Example Usage:

Start your backend API on port 8080
Run yarn start
Navigate to http://localhost:4200/#uri=/api
HAL Explorer will fetch data from localhost:8080/api without CORS issues

4.7. Development Server with Test Data

For frontend-only development, start the server with built-in test data:

yarn start:fs

Features:

All features of the basic development server
Built-in file server on port 3000
Example HAL and HAL-FORMS documents in test-data/ directory

Proxy Rules:

/test-data/ → http://localhost:3000/test-data/

Try It Out:

Navigate to http://localhost:4200/#uri=/test-data/movies.hal-forms.json to explore example HAL-FORMS data.

Available Test Files:

movies.hal-forms.json - HAL-FORMS with templates
options.hal-forms.json - HAL-FORMS with options
Various other example documents

4.8. Testing

HAL Explorer includes comprehensive unit and end-to-end tests.

4.9. Unit Tests

Interactive Mode (Default):

yarn test

Opens your default browser with the Karma test runner. Tests re-run automatically when files change.

Headless Mode (CI/CD):

yarn test:headless

Runs tests once in headless Chrome and exits. Perfect for continuous integration pipelines.

Additional Test Commands:

# Run tests with code coverage
yarn test:coverage

# Run specific test file
yarn test --include='**/app.component.spec.ts'

4.10. End-to-End Tests

yarn e2e

Runs the full E2E test suite using Playwright across multiple browsers (Chromium, Firefox, WebKit).

Requirements:

Playwright browsers installed (npx playwright install)

Additional E2E Commands:

# Run in headed mode (see the browser)
yarn e2e:headed

# Run only in Chromium
yarn e2e --project=chromium

# Debug mode with Playwright Inspector
yarn e2e:debug

See package.json for all available test options.

4.11. Building Documentation

Generate the complete reference documentation:

# Unix/Linux/macOS
./gradlew doc

# Windows
gradlew.bat doc

Troubleshooting (Windows):

If you encounter file encoding errors on Windows, use:

gradlew doc -Dfile.encoding=UTF-8

Output:

Documentation is generated in build/asciidoc/html5/ and includes:

Complete reference documentation
All included images and examples
Ready for deployment or local browsing

5. Frequently Asked Questions

5.1. General Questions

5.1.1. What is HAL Explorer?

HAL Explorer is a web-based tool for browsing and exploring RESTful Hypermedia APIs that use the HAL (Hypertext Application Language) and HAL-FORMS specifications. It provides an intuitive interface for navigating APIs by following links, viewing documentation, and testing different HTTP methods.

5.1.2. Do I need to install anything?

No installation required! You can use the hosted version at https://hal-explorer.com or GitHub Pages.

For backend integration, you can add HAL Explorer as a WebJar dependency or deploy the static files. See Backend Integration.

5.1.3. Is HAL Explorer free to use?

Yes, HAL Explorer is open source software licensed under the MIT License. You can use it freely for commercial and non-commercial projects. See License.

5.1.4. Which browsers are supported?

HAL Explorer works in all modern browsers:

Chrome/Chromium (recommended)
Firefox
Edge
Safari
Opera

Requires a browser with ES6 support and local storage capabilities.

5.1.5. Can I use HAL Explorer offline?

Yes, if you deploy HAL Explorer locally or integrate it into your backend. The hosted version requires internet access.

5.2. API Compatibility

5.2.1. Does my API need to support HAL or HAL-FORMS?

Yes, HAL Explorer is specifically designed for HAL and HAL-FORMS APIs. While it can display plain JSON, you won’t get the full functionality without proper HAL _links and _embedded structures.

5.2.2. What media types are supported?

HAL Explorer supports:

application/hal+json - Standard HAL
application/prs.hal-forms+json - HAL-FORMS
application/json - Plain JSON (limited functionality)

5.2.3. Do I need to modify my existing HAL API?

No modifications needed if your API already follows the HAL specification. HAL Explorer works with any compliant HAL API.

5.2.4. Can HAL Explorer work with non-HAL APIs?

HAL Explorer can display any JSON response, but without HAL’s _links structure, you won’t be able to navigate between resources or use hypermedia features. For non-HAL APIs, consider tools like Swagger UI or Postman.

5.2.5. Does HAL Explorer support other hypermedia formats?

No, HAL Explorer is specifically designed for HAL and HAL-FORMS

5.3. Features and Functionality

5.3.1. How do I authenticate with my API?

Click "Edit Headers" and add authentication headers:

Bearer tokens: Authorization: Bearer <token>
Basic auth: Authorization: Basic <credentials>
API keys: X-API-Key: <key> (or your API’s custom header)

See Customizing Request Headers for details.

5.3.2. Can I test POST, PUT, PATCH, and DELETE methods?

Yes! HAL Explorer supports all HTTP methods. Click the appropriate button next to any link:

< = GET
+ = POST
>> = PUT
> = PATCH
x = DELETE

For HAL-FORMS APIs, templates specify which methods are available.

5.3.3. How do I share my API exploration with colleagues?

HAL Explorer stores the current URI and custom headers in the URL fragment. Simply copy the URL from your browser’s address bar and share it. When opened, HAL Explorer will restore the same state.

Example:

https://hal-explorer.com/#uri=/api/customers&headers=...

Be careful sharing URLs with sensitive authentication tokens in headers.

5.3.4. Can I use HAL Explorer with APIs behind a VPN?

Yes, if you deploy HAL Explorer locally or integrate it into your backend that’s accessible within the VPN. The public hosted version cannot access VPN-protected resources.

5.3.5. Does HAL Explorer support pagination?

HAL Explorer can follow pagination links like next, prev, first, last if your API provides them in the _links section. Simply click the GET button next to the pagination link.

5.3.6. Can I view API documentation in HAL Explorer?

Yes! HAL Explorer supports CURIE-based documentation. If your API provides documentation links (via CURIEs), click the book icon next to any link relation to view inline documentation.

See CURIE-based Documentation.

5.4. HAL-FORMS Specific

5.4.1. What is HAL-FORMS?

HAL-FORMS is an extension to HAL that adds affordances (form templates) to describe how to interact with resources. It tells clients which HTTP methods, properties, and validations to use for operations like creating or updating resources.

Specification: https://rwcbook.github.io/hal-forms/

5.4.2. How do I know if my API supports HAL-FORMS?

Check if your API:

Returns Content-Type: application/prs.hal-forms+json
Includes a _templates object in responses
Documents support for HAL-FORMS

5.4.3. Do I need to request HAL-FORMS explicitly?

Some APIs automatically return HAL-FORMS. Others require you to request it via the Accept header:

Accept: application/prs.hal-forms+json

Add this in the "Edit Headers" dialog.

5.4.4. What are the benefits of HAL-FORMS over plain HAL?

HAL-FORMS provides:

Explicit affordances - Know exactly which HTTP methods are allowed
Property definitions - Type information, validation rules, constraints
Form generation - Auto-generated form fields in HAL Explorer
Options/enums - Dropdown menus for fields with predefined values
Better error messages - Client-side validation before sending requests

5.5. Technical Questions

5.5.1. Does HAL Explorer store my API data?

No. HAL Explorer is a client-side application. All API communication happens directly between your browser and your API server. No data passes through HAL Explorer’s servers (when using the hosted version).

Settings (theme, color mode, etc.) are stored in your browser’s local storage only.

5.5.2. How does HAL Explorer handle CORS?

HAL Explorer is a browser-based application and is subject to browser CORS policies. Your API must return appropriate CORS headers to allow access from HAL Explorer’s origin.

See CORS Troubleshooting for solutions.

5.5.3. Can I customize the appearance?

Yes! HAL Explorer offers:

Color modes - Light, Dark, or Auto (system preference)
27 themes - Bootstrap default plus 26 Bootswatch themes
Layout options - 2-column or 3-column layout

All settings persist across sessions.

5.5.4. Is my authentication token secure?

When using the hosted version:

They’re transmitted only to your API server
They appear in the URL fragment (be careful when sharing URLs)

For maximum security:

Use the hosted version only with development/test APIs
Deploy HAL Explorer within your own infrastructure for production use
Use short-lived tokens that expire quickly

5.5.5. Can I modify or extend HAL Explorer?

Yes! HAL Explorer is open source. You can:

Fork the repository
Make modifications
Build custom versions
Contribute improvements back

Repository: https://github.com/toedter/hal-explorer

5.5.6. How do I report bugs or request features?

Visit the GitHub issue tracker: https://github.com/toedter/hal-explorer/issues

Before creating a new issue:

Search existing issues
Check the Troubleshooting guide
Verify it’s a HAL Explorer issue (not an API issue)

5.6. Integration Questions

5.6.1. Can I integrate HAL Explorer into my Spring Boot app?

Yes! Multiple options:

WebJar - Add as a Maven/Gradle dependency
Spring Data REST Integration - Dedicated integration package
Static files - Copy built files to src/main/resources/static/

See Backend Integration for detailed instructions.

5.6.2. Can I use HAL Explorer with non-Java backends?

Absolutely! HAL Explorer is a pure client-side application. It works with any backend technology (Node.js, Python, Ruby, Go, .NET, etc.) as long as your API returns HAL-formatted responses.

5.6.3. Can I embed HAL Explorer in an iframe?

Yes, HAL Explorer can be embedded in an iframe. However:

Ensure your CSP (Content Security Policy) allows it
Configure appropriate CORS headers
Consider security implications of cross-origin embedding

5.6.4. Can I use HAL Explorer in my CI/CD pipeline?

HAL Explorer is primarily an interactive exploration tool. For automated API testing in CI/CD, consider:

REST Assured (Java)
SuperTest (Node.js)
pytest with requests (Python)
Other programmatic testing frameworks

HAL Explorer is best for manual testing, debugging, and API discovery.

5.6.5. How do I deploy HAL Explorer to my own server?

Download the distribution ZIP or build from source
Extract/copy files to your web server
Configure your web server to serve the files
Ensure proper routing for single-page application

See Static Distribution for examples.

5.7. Performance and Limitations

5.7.1. What’s the maximum response size HAL Explorer can handle?

HAL Explorer can handle large responses, but browser performance may degrade with:

Responses over 10MB
Thousands of embedded resources
Deeply nested structures (10+ levels)

For very large collections, implement pagination in your API.

5.7.2. How many simultaneous requests can HAL Explorer make?

HAL Explorer makes requests sequentially (one at a time) through the user interface. Browser limits on simultaneous connections to the same domain apply (typically 6-8 connections).

5.7.3. Does HAL Explorer support WebSockets or Server-Sent Events?

No, HAL Explorer only supports traditional HTTP request/response. For real-time features, use appropriate tools or libraries for your use case.

5.7.4. Can HAL Explorer handle binary data?

HAL Explorer is designed for JSON responses. It cannot display or handle binary data like images, PDFs, or file downloads. Binary data should be referenced via links rather than embedded in HAL responses.

5.8. Getting Started

5.8.1. I’m new to HAL - where should I start?

Read the HAL Specification
Try the demo with examples
Explore the included test data
Build a simple HAL API following tutorials
Explore your API with HAL Explorer

5.8.2. Where can I learn more about hypermedia APIs?

Resources:

Book: "RESTful Web APIs" by Richardson, Amundsen, and Ruby
Book: "Building Hypermedia APIs with HTML5 and Node" by Mike Amundsen
Website: HATEOAS Introduction
Course: Various REST and hypermedia courses on Udemy, Pluralsight
Specification: HAL Specification

6. Troubleshooting

This chapter helps you resolve common issues when using HAL Explorer.

6.1. Connection Issues

6.1.1. CORS Errors

Problem: Browser console shows CORS (Cross-Origin Resource Sharing) errors when trying to access your API.

Error Message:

Access to fetch at 'http://api.example.com/' from origin 'https://hal-explorer.com'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present
on the requested resource.

Solutions:

Enable CORS on Your Server (Recommended for development):

Add CORS headers to your API responses. See the CORS Setup section for Spring Boot examples.
Use the Development Server:

Clone HAL Explorer and run it locally with yarn start. The development server includes proxy configuration that avoids CORS issues. See Development Server.
Integrate HAL Explorer into Your Backend:

Deploy HAL Explorer as part of your application. See Backend Integration options.
Browser Extension (Development only):

Install a browser extension like "CORS Unblock" or "Allow CORS".

Only use CORS browser extensions for development. They disable important security features.

6.2. Getting Help

If you can’t resolve your issue:

Check Browser Console:

Open DevTools (F12) and look for errors in the Console and Network tabs.

Test with curl:

Verify your API works outside HAL Explorer:

curl -H "Accept: application/hal+json" http://your-api.com/endpoint

Report an Issue:

If you’ve found a bug in HAL Explorer, report it at: https://github.com/toedter/hal-explorer/issues

Include:
- HAL Explorer version
- Browser and version
- Steps to reproduce
- Error messages from console
- Example API response (if possible)
Ask the Community:

Check existing GitHub issues for similar problems and solutions.

7. License

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

HAL Explorer

Project Metadata

1. Introduction

1.1. What is HAL Explorer?

1.2. Why Use HAL Explorer?

1.3. Fundamentals

1.3.1. Prerequisites

1.3.2. Supported Media Types

1.4. Features Overview

1.4.1. User Interface

Theming and Appearance

Layout Options

1.4.2. API Interaction

HTTP Method Support

Request Customization

1.4.3. Advanced Features

Spring Data REST Integration

HAL-FORMS Support

Documentation Integration

Error Handling

1.4.4. Data Management

Browser Storage

Bookmarking and Sharing

1.4.5. Response Exploration

2. Setup and Installation

2.1. Quick Start: Online Demos

2.1.1. Using Online Demos with Your API

2.2. Backend Integration

2.2.1. Option 1: WebJar (Java Projects)

2.2.2. Option 2: Spring Data REST Integration

2.2.3. Option 3: Static Distribution

2.2.4. Option 4: Build from Source

3. Using HAL Explorer

3.1. Getting Started

3.1.1. Your First Request

3.2. Toolbar

3.2.1. Color Mode

3.2.2. Theming

3.2.3. Settings

Layout

Use HTTP OPTIONS

Enable all HTTP Methods for HAL-FORMS Links

3.2.4. About

3.2.5. Understanding the Interface

3.3. Working with Properties

3.4. Navigating Links

3.4.1. Link Display

3.4.2. HTTP Method Buttons

3.4.3. Following Simple Links

3.4.4. Working with Templated Links

3.4.5. Link Names and Titles

3.5. Exploring Embedded Resources

3.5.1. What Are Embedded Resources?

3.5.2. Viewing Embedded Resources

3.5.3. Navigating Embedded Resources

3.6. Inspecting Response Details

3.6.1. Response Status

3.6.2. Response Headers

3.6.3. Response Body

3.7. Curie-based Documentation

3.8. HAL-FORMS

3.9. Updating REST Resources

3.10. Customizing Request Headers

3.10.1. Opening the Headers Editor

3.10.2. Adding Custom Headers

3.10.3. Common Use Cases

Authentication

Content Negotiation

Custom Headers

3.10.4. Managing Headers

3.11. Configuration and Bookmarking

3.11.1. Bookmarking

3.12. HAL-FORMS Options

4. Development Setup

4.1. Prerequisites

4.2. Building for Production

4.3. Using Node.js/Yarn

4.4. Using Gradle

4.5. Development Server

4.6. Basic Development Server