This article provides instructions on creating a resource that will be represented by a JSON object. Resources that need to be represented in other formats will be other articles. This article will also focus on creating a resource based on a database table. Since the SRP HTTP Framework ships with a sample CONTACTS database table, we'll use it for our demonstration purposes. All of our examples will assume the following API is being called:
GET /contacts/1
Resources that are not based on data in a table can still use some of the principles presented below, but there will need to be a little more effort. We will provide additional articles to demonstrate how non-database resources can be created.
The Resource Object
We've already explained that a resource can be represented in any digital format, but the conventional format used by RESTful APIs is to use JSON. In our documentation we will often make reference to the resource object, which is short-hand for the "resource as represented by a serialized JSON object".
Have it Your Way
There are four basic methods for creating a resource within the SRP HTTP Framework. You will choose the method that best suits your needs. We will list the pros and cons of each method and provide sample code that creates the same resource using each method.
Method 1: Using the GetDatabaseItem Service
For simple database related resources, the GetDatabaseItem service (a member of the HTTP_Resource_Services module) can be used with minimal code. Just get the Key ID from the prepopulated EndpointSegment variable and pass in the name of the database table:
API contacts.ID.GET
KeyID = EndpointSegment
HTTP_Resource_Services('GetDatabaseItem', 'CONTACTS', '', KeyID)
end api
This produces the following resource object:
{
"address":"6649 N Blue Gum St",
"birthdate":"",
"city":"New Orleans",
"company":"Benton, John B Jr",
"county":"Orleans",
"email":"jbutt@gmail.com",
"first_name":"James",
"last_name":"Butt",
"notes":"",
"picture":"\\WebAppData\\ContactPictures\\1.jpeg",
"state":"LA",
"url":"http://www.bentonjohnbjr.com",
"zip":"70116",
"phone":[
{
"phone_number":"(504) 621-8927",
"phone_type":"Phone 1"
},
{
"phone_number":"(504) 845-1427",
"phone_type":"Phone 2"
}
]
}
One of the drawbacks of calling the GetDatabaseItem service is that property names are formatted with underscores (i.e., how they appear in the dictionary) rather than as camel case (which is the conventional format for JSON objects). Another drawback is that the GetDatabaseItem service attempts to create a resource object from all column data (both physical and calculated). This might be undesirable if some of the data is meaningless to the client. Consider the picture property in the above resource object. It references an image file stored locally on the server, which has no value to the client. This can also be problematic if a calculated column encounters a runtime error or is dependent upon information that only exists within an OpenInsight desktop session. To resolve both of the above items, we will take advantage of the optional ColumnNames and ItemArrayLabel arguments. To keep our sample code simple and concise, we will limit our resource to just the FIRST_NAME, LAST_NAME, ADDRESS, CITY, STATE, and ZIP database columns:
API contacts.ID.GET
KeyID = EndpointSegment
ColumnNames = 'FIRST_NAME' : @FM : 'LAST_NAME' : @FM : 'ADDRESS' : @FM : 'CITY' : @FM : 'STATE' : @FM : 'ZIP'
ItemArrayLabel = 'firstName' : @FM : 'lastName' : @FM : 'address' : @FM : 'city' : @FM : 'state' : @FM : 'zipCode'
HTTP_Resource_Services('GetDatabaseItem', 'CONTACTS', '', KeyID, ColumnNames, ItemArrayLabel)
end api
Our resource object now appears like this:
{
"address": "6649 N Blue Gum St",
"city": "New Orleans",
"firstName": "James",
"lastName": "Butt",
"state": "LA",
"zipCode": "70116"
}
Pros:
- Simple to call.
- It creates the Response Body and Content-Type Header automatically.
Cons:
- Deprecated (but there are no plans to remove it).
- HATEOAS support is limited.
- Cannot include the Key ID within the resource object.
Method 2: Using the GetObject Service
GetDatabaseItem is an example of a high-level service. That is, it relies upon a simple interface and default behavior. Like other high-level services, GetDatabaseItem is built on top of slightly lower-level services. The most important one of these is GetObject. (which is also a member of the HTTP_Resource_Services module). Let's look at an example of an API that uses the GetObject service to produce the same resource as the GetDatabaseItem service:
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
// 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
In many ways, GetObject and GetDatabaseItem are the same, including sharing many of the same arguments. GetObects differs from GetDatabaseItem in the following ways:
- GetDatabaseItems returns the resource object in serialized JSON (i.e., stringified JSON) whereas GetObject returns a handle to the JSON object.
- GetDatabaseItems automatically updates the Response Body with the resource object and the Content-Type Header whereas GetObject leaves this to the calling process to handle.
- GetDatabaseItems will create a self and a collection HATEOAS links if the optional SelfURL argument is used whereas GetObject only creates a self HATEOAS link.
This produces the following resource object:
