On its own, information represented in resource objects is simply media. However, in order to encourage client exploration and access to related resources we need to add hypermedia to our resources. RESTful API developers often abandon HATEOAS implementation because it can be considered more effort than it is worth. The SRP HTTP Framework makes this much easier through the use of automation and dedicated services.
Using the AddLinkRelationship Service
In our How do I create a resource? article we introduced the GetObject service as a primary method for creating resource objects. To keep our documentation focused on creating a resource objects, we did not introduce hypermedia. Now we will use the same code sample and introduce a new service: AddLinkRelationship:
API contacts.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', 'CONTACTS', KeyID, ColumnNames, PropertyNames) If Error_Services('NoError') then // Add _links sub-properties for HAL implementation. HTTP_Resource_Services('AddLinkRelation', objResource, 'self', FullEndpointURL) HTTP_Resource_Services('AddLinkRelation', objResource, 'collection', ParentURL) 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
By using the FullEndpointURL and the ParentURL prepopulated variables, we automatically have the self and collection hypermedia ready to add to the reserved _links property:
{ "address":"6649 N Blue Gum St", "city":"New Orleans", "firstName":"James", "lastName":"Butt", "state":"LA", "zipCode":"70116", "_links":{ "self":{ "href":"https://www.examples.org/customers/1" }, "collection":{ "href":"https://www.examples.org/customers" } } }