Page History

In our What is a resource? article we noted that a resource is digital content which can be represented by various media types. Most of the time this will be text based media (e.g., HTML, JSON, XML). However, there will be situations when the resource needs to be represented by binary media. Here are a few possible use cases:

• A customer wants to download a PDF version of a customer an invoice.
• A JPEG traveler boarding a plain needs to display a scannable image of a barcodebar code.
• An MPEG A worker wants to watch a video of assembly instructions.

The SRP HTTP Framework includes a routine called sample Picture _ API. It includes logic that returns a graphic image associated with the indicated sample contact. Regardless of the specific binary media type, head shot graphics for the sample Contacts resource. Reviewing this code (found in the PICTURE_API routine) will be useful to see how a fully integrated image API can be written, we'll summarize below the basic steps for returning binary media in your API are the same.

Step One: Read the Binary Data

Your binary data needs to be read into a variable. Typically this will be done using the OSRead statementSome applications store binary media inside of an OpenInsight database so a Read statement might be used. The Picture API assumes its images are stored in a specific OS folder, so it uses an OSRead statement instead. Here is the relevant code from the Picture API:

...

Step Two: Set the Response Body.

As with text based media, use the SetResponseBody service to identify the content to be returned to the caller:

HTTP_Services('SetResponseBody', PictureBinary)

Step Three: Identify the Response as Binary

The above SetResponseBody example uses proper syntax and would work adequately for most text based media, but binary media needs to be packaged differently for the OECGI to return it correctly. This is done by setting the IsBinary argument to a 1:

Equ True$ to 1
HTTP_Services('SetResponseBody', PictureBinary, True$)

Step Four: Set the Correct Content-Type

Although our response will now be properly packaged up as binary, the client will likely not be able to process the media properly. Should it attempt to display this as a PDF document? Should it attempt to play this as a video? Clients normally need this additional metadata, therefore the Content-Type response header needs to be set with the appropriate IANA media type. There are two ways of doing this. One way is to use the SetResponseHeaderField service and type in the field name (i.e., Content-Type) and field value (e.g., image/jpeg). The easier way is to use the ContentType argument that has been provided with the SetResponseBody service. The following updated code sample uses this latter method:

Equ True$ to 1
HTTP_Services('SetResponseBody', PictureBinary, True$, 'image/jpeg')