1

We are designing an API to support configuring and running a report that is based on many parameters, some of which have many (thousands of) multi-selectable values. I am looking for a way to offer up these options in something other than individual links.

First, we want to walk them through the parameters (which I'm thinking of as sub-resources) in an ordered way b/c of dependencies

POST v1/reports/GUID/parm1 w/ JSON payload {parm1: value1}
POST v1/reports/GUID/parm2 etc

At some point parmX will have many options. Let's say parmX-1 was submitted, we want to present them some list of (many), multi-selectable values for parmX, and they would do something like:

POST v1/report/GUID/parmX w/ JSON payload {parmsX: [valueA, valueB, ..., valueC]}

I don't see anyway to do this other than present the options in the response (to the parmX-1 request) as some kind of JSON object and maybe some properties that tie it to the actual links served up.

Is this just one of those things that falls under the "sometimes you kind of have to break HATEOAS and document it in your API"?

user2457760
  • 1
  • 5
  • How would you solve it in Web pages? The same approach (and concepts) apply to REST as well. For the Web you'd probably return a form the user has to enter values to certain fields. In REST either reuse HTML forms, or a similar approach such as [halo+json](https://gist.github.com/mikekelly/5619934) or define your own media-type that describes how options and selections should look like so that your UI can present them to a user. Such a custom media-type should be registered with [IANA](https://www.iana.org/assignments/media-types/media-types.xhtml) though – Roman Vottner Apr 02 '19 at 00:15
  • Where is halo+json spec'd? I don't see it on that IANA link. And I am imagining customer media that looks very similar to it. – user2457760 Apr 02 '19 at 00:48
  • Unfortunately, there is no official spec yet out there AFAIK other than some basic [example](http://halform.herokuapp.com/), but you can have a look at [this question](https://stackoverflow.com/questions/55315913/hateoas-and-forms-driven-by-the-api) to learn a couple other media types that have support for similar stuff. – Roman Vottner Apr 02 '19 at 00:52
  • Thanks. One (big?) difference between our reqs and that form-like halo+json, is that we have dependencies such that if you change, for example, a selection on parm1, then the allowed values for parm2 might not only be different, but an entirely different type. In our current proprietary version we can control this client-side and refresh parm2 dynamically. But we can't allow arbitrarily selection and submission of all the form's controls at once. – user2457760 Apr 02 '19 at 16:27
  • I don't really get your point here TBH. The form is a generic description of what the server expects as input from the client. It is not tied to a particular object type on your server side. Of course you need to be able to map your model to a representation of the form. This could be based on looking what fields the object has via reflection and generating a form based on the types the fields have. Certain annotations might be used to skip certain fields or to map them to other "widget" elements. I'm not 100% what you mean by `entirely different type` though ... – Roman Vottner Apr 02 '19 at 16:38
  • One selection might be "include widgets of Type1, Type2, ... TypeN", where only one can be selected. Then the subsequent selection might change from offering widgets of Type1 to those of Type2. – user2457760 Apr 02 '19 at 20:27
  • Probably the cleanest approach as far as I understood your requirements would be to split the form up into multiple ones and chain them together depending on the choices selected in previous steps. This is somehow like a typical installation wizard then where you hop from one form to the next until you have everything together. If you know that your client also supports Javascript you might return HTML with Javascript code that dynamically disables elements not selected. Though the actual HTML generated would have to include each option then as you don't know what the client might chose. – Roman Vottner Apr 02 '19 at 21:08

0 Answers0