Page History

...

• Custom control over the creation of the resource object.
• Ability to include the Key ID within the resource object.
• Ability to identify a part of a Key ID as the resource ID.
• Lower-level errors can be trapped and handled as desired.
• The handle to the JSON object is compatible with the SRP_JSON utility function (for even more custom control as needed)Can use the SRP_JSON member services for additional functionality.

Cons:

• Caller must serialize the JSON object.
• Caller responsible for setting HTTP response elements.

...

When complete control at the lowest level is required, you'll want to use SRP_JSON to create your resource. As noted above, the handle returned by the GetObject service is compatible with the SRP_JSON function and vice-versa. Therefore, a developer can choose to start with either method and continue to use the use SRP_JSON member services and the higher level GetObject companion services (e.g., AddProperty, AddSubProperty, etc.) at will. One unique feature of SRP_JSON is its ability to interrogate the resource object using services like GetValue. This is useful when a resource object is generated elsewhere. Examples of how this can work will be documented in another article. For instance, let's assume that a resource object was created by another service and it returns a handle. The calling routine now needs to modify this resource object, but only if it has specific data already in it. The GetObject companion services can only update resource objects, not inspect them. This requires the assistance of one or more of the SRP_JSON member services.now, here is an example of how our sample resource could be created primarily from SRP_JSON:

API contacts.ID.GET

API contacts.ID.GET

    KeyID           = EndpointSegment

    // Create a JSON object in memory.
    If SRP_JSON(objResource, 'New') then
        ContactRow  = Database_Services('ReadDataRow', 'CONTACTS', KeyID)
        If Error_Services('NoError') then
            SRP_JSON(objResource, 'SetValue', 'firstName', ContactRow<CONTACTS_FIRST_NAME$>, 'String')
            SRP_JSON(objResource, 'SetValue', 'lastName', ContactRow<CONTACTS_LAST_NAME$>, 'String')
            SRP_JSON(objResource, 'SetValue', 'address', ContactRow<CONTACTS_ADDRESS$>, 'String')
            SRP_JSON(objResource, 'SetValue', 'city', ContactRow<CONTACTS_CITY$>, 'String')
            SRP_JSON(objResource, 'SetValue', 'state', ContactRow<CONTACTS_STATE$>, 'String')
            SRP_JSON(objResource, 'SetValue', 'zipCode', ContactRow<CONTACTS_ZIP$>, 'String')
            // Serialize the JSON object and release the object from memory.
            jsonResource    = SRP_JSON(objResource, 'Stringify', 'Fast')
            SRP_JSON(objResource, 'Release')
            // 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 reading the CONTACTS row. Probably a non-existent row.
            HTTP_Services('SetResponseError', '', '', 404, 'Contact ' : KeyID : ' does not exist.', FullEndpointURL)
        end
    end else
        // There is an error condition so call the SetResponseError service.
        HTTP_Services('SetResponseError', '', '', 500, 'Unable to create JSON object', FullEndpointURL)
    end

end api

There are a few items about this sample code that need to be pointed out:

• The above represents one way of utilizing SRP_JSON but is certainly not the only way.
• The CONTACTS database row is read using the ReadDataRow service (a member of the Database_Services module). This service module ships with the SRP HTTP Framework but is not required. The row can be read using any statement, SSP, or custom written stored procedure.
• The success of the ReadDataRow service is confirmed using the NoError service (a member of the Error_Services module). This service module ships with the SRP HTTP Framework but is not required.

Pros:

• All the benefits of the GetObject service method.
• Can use the GetObject companion services for convenience.
• Provides access to services that can interrogate the handle to the resource object.

Cons:

• Caller must serialize the JSON object.
• Caller responsible for setting HTTP response elements.
• Caller must handle errors with SRP_JSON services directly.
• Object handle to SRP_JSON must be released directly.
• Uses generic JSON terminology rather than resource object terminology.