Clarification on Correct Usage of HAL-Forms for Editing Resources

[kalgon]

I have a question regarding the usage of HAL-Forms.

Scenario: Creating a Customer

When managing a list of customers through an API, I can fetch a form definition for creating a new customer like this:

GET /api/customers
Accept: application/prs.hal-forms+json

Response:

{
  "_links": {
    "self": { "href": "/api/customers" }
  },
  "_templates": {
    "default": {
      "title": "Create customer",
      "method": "POST",
      "contentType": "application/json",
      "properties": [
        { "name": "name", "required": true, "prompt": "Name" },
        { "name": "vat", "required": true, "prompt": "VAT", "type": "number" }
      ]
    }
  }
}

This seems straightforward—it's a form template for creating a new customer.

Question: Editing a Customer

When editing a customer, I’m not sure about the correct approach. Should I retrieve a pre-filled form with the current customer data, like this?

GET /api/customers/1
Accept: application/prs.hal-forms+json

Response:

{
  "_links": {
    "self": { "href": "/api/customers/1" }
  },
  "_templates": {
    "default": {
      "title": "Edit customer",
      "method": "PUT",
      "contentType": "application/json",
      "properties": [
        { "name": "name", "required": true, "prompt": "Name", "value": "ACME" },
        { "name": "vat", "required": true, "prompt": "VAT", "type": "number", "value": "123456789" }
      ]
    }
  }
}

Or, is it more appropriate to separate the form definition from the actual data and combine them client-side?

For instance, I could get the form definition and data separately:

1. Form Definition:

GET /api/customers
Accept: application/prs.hal-forms+json

Response:

{
  "_links": {
    "self": { "href": "/api/customers" }
  },
  "_templates": {
    "create": {
      "method": "POST",
      "contentType": "application/json",
      "properties": [...]
    },
    "edit": {
      "method": "PUT",
      "contentType": "application/json",
      "properties": [...]
    }
  }
}

2. Customer Data:

GET /api/customers/1
Accept: application/json

Response:

{ "name": "ACME", "vat": 123456789 }

Current Dilemma

I’ve always assumed that pre-filling the form with existing data (as in the first example) is the correct approach. However, I’m now working with Spring HATEOAS, which can infer form definitions from Java classes but doesn’t seem to offer a way to return pre-filled forms. This has led me to wonder if I’m misunderstanding the intended usage of HAL-Forms, or if the issue lies within Spring HATEOAS itself.

Has anyone else encountered this, or can you clarify the correct approach for handling pre-filled forms when editing resources?

[wertzui]

I've encountered the same question and after asking in the (now hut down Googe Group), I got the response that both are possible.

For myself I took a "hybrid" approach.

When getting a single resource (one book), I pre fill the form. When getting a list of resources (all books), I send along 2 empty templates. I named them "search" and "edit". I display those lists in a table and the search template defines how the table-header is rendered where the user can click on to filter and sort the table. The edit template then defines how the table rows are rendered. Some properties might be read-only while some might be writable (depends on the use case).