Page History

...

• 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)

In the above example, the intent of this form action is to describe how a new phone number can be added to the current resource. Clients should be able to consume this meta data and discover that this is done by sending a JSON object containing the type and number properties via a POST to the indicated URI.

fields Sub-Property

The fields sub-property contains one or more sub-properties. Each of these sub-properties are the names of a property in the primary resource object. In the above example, type and number are expected to be properties within the primary resource object. The sub-property values are themselves additional sub-property name/value pairs.

Each defined field name contains one or more of the following sub-properties:

• default to indicate the value of the resource object property that should be submitted unless overridden by the client.
• required to indicate that this resource object property must have a value in order for the form action to be accepted.
• visible to indicate if this resource object property should be visible to the client.

Hierarchical Outline

To help visualize the _forms structure, here is a general outline:

• _forms
  • form action 1
    
    • method
    • action
    • title
    • fields
      
      • field 1
        
        • default
        • required
        • visible
      • field 2
        
        • default
        • required
        • visible
  • form action 2
    • method
    • action
    • title
    • fields
      
      • field 1
        
        • default
        • required
        • visible
      • field 2
        
        • default
        • required
        • visible

Using the AddFormAction Service

With our background out of the way, we can now demonstrate how to call the AddFormAction service. To make this easy, we'll implement the form action that appears in the above example:

API customers.ID.GET

    KeyID           = EndpointSegment
    
    ColumnNames     = 'FIRST_NAME' : @FM : 'LAST_NAME' : @FM : 'ADDRESS' : @FM : 'CITY' : @FM : 'STATE' : @FM : 'ZIP'
    PropertyNames   = 'firstName' : @FM : 'lastName' : @FM : 'address' : @FM : 'city' : @FM : 'state' : @FM : 'zipCode'
    // Create a JSON object in memory.
    objResource = HTTP_Resource_Services('GetObject', 'CUSTOMERS', KeyID, ColumnNames, PropertyNames)
    
    If Error_Services('NoError') then
        // Add _forms sub-property hypermedia control.
        Fields          = 'type' : @FM : 'number'
        FieldProperties = 'Cell' : @VM : True$ : @VM : True$ : @FM : '' : @VM : True$ : @VM : True$
        HTTP_Resource_Services('AddFormAction', objResource, 'addPhone', 'POST', FullEndpointURL, 'Add Phone', Fields, FieldProperties)
    end
    
    If Error_Services('NoError') then
        // Serialize the JSON object.
        jsonResource    = HTTP_Resource_Services('GetSerializedResource', objResource)
        // Set the response body with the serialized JSON object and set the Content-Type response header.
        HTTP_Services('SetResponseBody', jsonResource, False$, 'application/hal+json')
    end else
        // There is an error condition so call the SetResponseError service.
        HTTP_Services('SetResponseError', '', '', 500, Error_Services ('GetMessage'), FullEndpointURL)
    end
    
end api