0

For simplicity's sake, let's say we are storing users' personal informations like so (JSON here, but that's not the point):

{
    "name": "John"
    "age": 35
    "sex": "M"
}

We want to have the UI client to create a form in order to display these infos and also for creating new users or updating existing ones.

So, my question is:

How can this be achieved in a RESTful manner? Does REST even provide for such type of interactions, that is, hinting clients on how to display the resources provided?

We would like to give clients maximum freedom on how to represent resources but also to help them send us back the correct data without too much coupling between backend and frontend.

For example, we could have a template for user like so:

{
     "self": "/template/user"
     "method": "GET"
     "data": {
         "fields": [
              {
                  "name": "name"
                  "value": {
                      "data_type": "string"                      
                  }
              },
              {
                  "name": "age"
                  "value": {
                      "data_type": "number"                      
                  }
              },
              {
                  "name": "sex"
                  "value": {
                      "data_type": "string"
                      "options": [
                          "M",
                          "F"
                      ]

                  }
              }
         ]
    }
}

Thank you for any input you might be able to provide.

Johnny
  • 1,063
  • 1
  • 11
  • 23
  • As your sample contains JSON you might have a look at [json-schema](http://json-schema.org/) to describe the actual valid input or expected fields of a request. For XML based messages you may use XSD (or DTD) to teach the client what it is expected to send. For other document types though it gets a bit less clear on how to teach/support a client. Clients may though need a special media type to be able to support these capabilities as with default media types (i.e. `application/json`) they might not respect these schemas out of the box – Roman Vottner Dec 19 '16 at 11:30
  • As my previous comment was more related on the "teach the client on what to send back" concern and less on the view-support, my comment might not have helped you much I guess. If an API or server should help a client in hinting clients on how to present forms, why not send specific HTML output (including the form) from the server to the client? If the client is a browser (or browser-aware component), presenting the form is just a simple render of the response. The client can either request help via content negotiation (`text/html`) or do its own stuff (`application/json`) – Roman Vottner Dec 19 '16 at 11:39
  • Thank you very much, but see my comment to @voiceofunreason answer to see why I was trying to avoid sending HTML. – Johnny Dec 19 '16 at 18:16

1 Answers1

0

How can this be achieved in a RESTful manner? Does REST even provide for such type of interactions, that is, hinting clients on how to display the resources provided?

The reference application for REST is the world wide web; how did we do it there?

1) we used a media type (HTML) that supported in band presentation instructions that could, at the client's discretion, be interpreted by the client's choice of rendering engine

2) we provided links to ancillary resources (CSS) that could optionally be fetched to provide additional presentation hints to the rendering engine.

Note that this depended on text/html and text/css being well defined (standardized) so that rendering engines (browsers) could be developed independently from the servers.

I haven't seen any alternatives to HTML as a standard for sharing rendering instructions with the client. My suggestion as a first approach would be to link your data representation to an html representation, that can be used by clients that understand rendering.

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • Both you and @RomanVottner are suggesting to send HTML. While I fully understand why, I was trying to avoid exactly this because I wanted to give the client maximum freedom. For example `options` might be rendered as select drop-downs or radio buttons. If I "force" the client to use one representation in favor of another I will ultimately limit it. – Johnny Dec 19 '16 at 18:14