Page History

Versions Compared

Key

This line was added.
This line was removed.
Formatting was changed.

...

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:

Code Block

language	bp

API contactscustomers.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', 'CONTACTSCUSTOMERS', 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

...

HAL also supports the _embedded reserved property, which is a way to include partial or whole resources within the primary resource object. These embedded resources are themselves stand-alone resources with their own endpoints. The usual reason they are embedded is so the client does not have to make multiple requests to get this same resource information. This is common with collection APIs (e.g., GET /customers). The following code sample uses the GetObjects service to return an array of contacts customers resource objects. These are then embedded into the primary resource object using the AddEmbeddedResources service:

Code Block

language	bp

API contactscustomers.GET

    // Create the primary resource object.
    objResource     = HTTP_Resource_Services('GetObject')
    If Error_Services('NoError') then
        // Create the sub-resource objects.
        objSubResources = HTTP_Resource_Services('GetObjects', 'CONTACTSCUSTOMERS', '', 'FIRST_NAME' : @FM : 'LAST_NAME', 'firstName' : @FM : 'lastName', '', '', '', FullEndpointURL)

        If Error_Services('NoError') then
            // Pass the sub-resource object list to the AddEmbeddedResources service. Use the 'contactscustomers' label to identify the type of sub-resource.
            HTTP_Resource_Services('AddEmbeddedResources', objResource, 'contactscustomers', objSubResources)
        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


end api

This API would return the following resource object:

Code Block

language	js

{
   "_embedded":{
      "contactscustomers":[
         {
            "firstName":"Harrison",
            "lastName":"Haufler",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/266"
               }
            }
         },
         {
            "firstName":"Haydee",
            "lastName":"Denooyer",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/271"
               }
            }
         },
         {
            "firstName":"Heike",
            "lastName":"Berganza",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/254"
               }
            }
         },
         {
            "firstName":"Helga",
            "lastName":"Fredicks",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/202"
               }
            }
         },
         {
            "firstName":"Herman",
            "lastName":"Demesa",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/125"
               }
            }
         },
         {
            "firstName":"Herminia",
            "lastName":"Nicolozakes",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/287"
               }
            }
         },
         {
            "firstName":"Hillary",
            "lastName":"Skulski",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/186"
               }
            }
         },
         {
            "firstName":"Howard",
            "lastName":"Paulas",
            "_links":{
               "self":{
                  "href":"https://www.examples.org/api/customers/132"
               }
            }
         }
      ]
   }
}

Using the GetDatabaseItems Service

Code Block

language	bp

API customers.GET

    jsonResource    = HTTP_Resource_Services('GetDatabaseItems', '', 'CUSTOMERS', FullEndpointURL, 'FIRST_NAME' : @FM : 'LAST_NAME', 'firstName' : @FM : 'lastName')

    If Error_Services('NoError') then
        // 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

Content

Space Tools

Versions Compared

Old Version 8

New Version 9

Key

Using the GetDatabaseItems Service