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. The AddLinkRelationship service creates the HAL _links reserved property:
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 relations ready to add to the _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"
}
}
}
There is also a AddLinkRelations service. It's a wrapper around the AddLinkRelation service that allows the developer to pass in an @FM delimited list of relations and URLs into a single call. Developers will need to decide if the AddLinkRelations service provides enough convenience in lieu of multiple AddLinkRelation calls.
