How do I add hypermedia controls to a resource?

Background

We've already discussed how to add hypermedia to a resource using the standard HAL _links and _embedded reserved properties. These properties will cover the majority of your hypermedia needs. However, in this same article we introduced the AddFormAction service to address hypermedia requirements that go beyond the design intent of the _links and _embedded properties.

To understand the AddFormAction service, it is important to understand the inspiration behind its design: HTML. As most developers will recognize, HTML is both a media type and a markup language. Because it is a media type, we can borrow from its well defined and understood hypermedia controls when defining similar capabilities for the JSON media type. In HTML, we find that hypermedia controls are used for three general purposes:

1. To identify related resources through hyperlinks that allow the client to change the application state (e.g., the <a> tag).
2. To embed resources from another URI into the current resource (e.g., the <img> tag).
3. To provide the client input and submit capabilities to interact with the current resource (e.g., the <form> tag.)

It would seem that HAL covers the first two purposes reasonably well. The _links property provides the same purpose as the <a> tag and the _em bedded property provides the same purpose as tags like <img> (which is just one of a few tags that embed resources). However, the third purpose - the ability to provide richer interaction with the resource via form-like controls - is not addressed by HAL.

New Reserved Property: _forms

In keeping with the spirit of HTML hypermedia controls, the SRP HTTP Framework supports a custom property called _forms. It serves the same purpose as the HTML <form> tag and borrows some of the same element names. Here is an example of what _forms hypermedia controls looks like:

{  
   "_forms":{  
      "addPhone":{  
         "method":"POST",
         "action":"https://www.examples.org/api/user/matthew/phone",
         "title":"Add Phone",
         "fields":{  
            "type":{  
               "default":"Cell",
               "required":true,
               "visible":true
            },
            "number":{  
               "default":"",
               "required":true,
               "visible":true
            }
         }
      }
   }
}

The _forms property contains one or more sub-properties. Each sub-property name defines a unique form action and is typically named in a verb+noun format (e.g., addPhone in the above example). The sub-property values are themselves additional sub-property name/value pairs.

Each defined form action contains the following sub-properties:

• method to indicate the HTTP method used when making the request to the server. (Required)
• action to indicate the target URI for the request. (Required)
• title to provide a user-friendly label for the form action. (Optional)
• fields to identify relevant properties from the primary resource object and to document how they are to be handled. (Optional)