Awasu » Using the Awasu API: Customizing the API
Sunday 5th July 2015 11:55 PM []

The responses returned by the Awasu API are all generated from templates, and you will find these files in C:\Program Files\Awasu\Resources\API\.

Response files are organized by their base filename, and extension. For example, the highlighted files in the screenshot are the templates for $/buildInfo call, in HTML, JSON and XML formats.

When Awasu receives an API request, it uses the main part of the URL to figure out which template file to generate the response from [1]For example, calling http://localhost:2604/channels/list will use one of the channels-list template files., and the format parameter as the filename extension [2]For example, calling http://localhost:2604/channels/list?format=json will use the channels-list.json template file.

This means that it's really easy to return responses in different formats.

First, let's take a look at one of the existing template files, :

{ "buildInfo":
{

"version": "{%VERSION-STRING%}" ,
"isService": "{%IS-SERVICE%}" ,
"isTrial": "{%IS-TRIAL-VERSION%}" ,
"buildDate": "{%BUILD-DATE% format=datea_time}" ,
"buildDateTimestamp": {%BUILD-DATE% format=time_t} ,
{%?EXPIRY-DATE%}
"expiryDate": "{%EXPIRY-DATE% format=datea}" ,
"expiryDateTimestamp": {%EXPIRY-DATE% format=time_t} ,
{%ENDIF%}
"httpUserAgent": "{%HTTP-USER-AGENT%}"

...snip...

The things like {%VERSION-STRING%} and {%BUILD-DATE% format=datea_time} are placeholders, that Awasu will replace with the real values when it generates the response.

Let's say we want to add a version of the $/buildInfo API call that returns the information in plain-text. We create a file called buildInfo.txt that looks something like this:

You are running Awasu {%VERSION-STRING%}.

It was built on {%BUILD-DATE% format=datea_time}.

Save it with the the other template files [3]Namely, in C:\Program Files\Awasu\Resources\API\., and open the following URL in a browser [4]You don't even need to restart Awasu ::-): :

    http://localhost:2604/buildInfo?format=txt 


And tada, Awasu is now returning the build information using our new template [5]Awasu selected our buildInfo.txt template file because we specified format=txt in the request URL..

However, the formatting is not quite right, since Awasu has not set a MIME type when it sends the response, but we can work around this by adding a pseudo-placeholder in the template file:

{%SET-CONTENT-TYPE% text/plain}

This tells Awasu to return the response as text/plain, and the browser now understands properly how to display the content.

Download the source code here.



   [ + ]

1. For example, calling http://localhost:2604/channels/list will use one of the channels-list template files.
2. For example, calling http://localhost:2604/channels/list?format=json will use the channels-list.json template file.
3. Namely, in C:\Program Files\Awasu\Resources\API\.
4. You don't even need to restart Awasu ::-):
5. Awasu selected our buildInfo.txt template file because we specified format=txt in the request URL.
Have your say