HAL-FORMS: How to define arbitrary key/value pairs as properties in a template?

31 views
Skip to first unread message

Icke Bins

unread,
Oct 26, 2021, 7:53:16 AM10/26/21
to HAL Discuss

It should be possible to define properties which accept arbitrary key/value pairs. For example when the server accepts a Map as request body.

example:

Server accepts:

POST /foo 
key1=value1&key2=value2,...

Any idea how to define it in a template?

Thank you

Patrick Moule

unread,
Oct 27, 2021, 3:17:22 AM10/27/21
to HAL Discuss
Hi,

I'm not sure, if I get you right.

If you want to define a template with HAL-FORMS for accepting simple key / value pairs in a HTTP message's body, then 
setting contentType as 'application/x-www-form-urlencoded' should fit.

Example:
"_templates" : {
    "default" : {
      "title" : "Create",
      "method" : "POST",
      "contentType" : "application/x-www-form-urlencoded",
  "target" : "/foo"
      "properties" : [
        {"name" : "key1"},
        {"name" : "key2"}
      ]
    }
  }

Best regards
Patrick

Icke Bins

unread,
Oct 27, 2021, 12:02:12 PM10/27/21
to HAL Discuss
key1, key2 was just an example. The name of the properties could be any name, not just key1, key2. 

mca

unread,
Oct 27, 2021, 12:28:14 PM10/27/21
to hal-d...@googlegroups.com
your example looks like it's covered by the existing spec, right? 

Mike Amundsen



--
You received this message because you are subscribed to the Google Groups "HAL Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/f9f41051-92b8-42fc-990e-015c16b5fd07n%40googlegroups.com.

Patrick Moule

unread,
Oct 27, 2021, 2:03:20 PM10/27/21
to HAL Discuss
Ok got it. Can you please provide more details about the purpose and why in your opinion HAL-FORMS should have the possibility to deal with arbitrary key / value pairs.

IMO the support of dynamic UI forms is the main motivation for using HAL-FORMS. So, at least one named property would make sense - I may miss any other use cases.

Icke Bins

unread,
Oct 28, 2021, 5:33:49 AM10/28/21
to HAL Discuss
Some of our business objects allow customer specific arbitrary key/values pairs stored as settings, like:

POST /foo/1/settings
customerSetting1=value1& customerSetting2=value2

while other customers/tenants may use:

POST /foo/2/settings
mySetting1=value1&mySetting2=value2

Which keys and values are used is decided by the customer.

Patrick Moule

unread,
Oct 28, 2021, 8:46:29 AM10/28/21
to HAL Discuss
In your case I would provide a form with a single "settings" property of type "map". 
Message's body could then contain just key/value pairs or JSON, but that's all up to you and depends on the used content type.

IMO that's a feasible way with current HAL-FORMS specification.

Example:
"properties" : [
{"name" : "settings", "type" : "map"} 
]

Best
Patrick

Icke Bins

unread,
Oct 29, 2021, 4:56:18 AM10/29/21
to HAL Discuss
Yes, this was my thought too. Same for lists:

POST /foo
key=1&key=2

How to define the data type of the values? map<text>, list<number>?

Patrick Moule

unread,
Oct 30, 2021, 4:07:07 AM10/30/21
to HAL Discuss
I personally think, this depends on consumers of your API. I would propose to provide as much information in your type to foster API users to provide valid values.
Reply all
Reply to author
Forward
0 new messages