Response transforms

When the response from an API is not in the correct format for immediate use Api2File allows a data transform to be applied, changing the data into a more useful shape.

Transforms are applied to textural data only. They cannot be applied to binary data (e.g. images, applications or videos). However, they use a powerful transformation engine running within Api2File which allows almost limitless customisation of the data to be presented as text.

Api2File transforms are applied per file share. Meaning the same data can be presented in many different ways to consumers by creating a new share referring to the same API endpoint, but with a different transform.

It should be noted that although most transforms will be applied quickly, resulting in minimal delay before downloading commences, if an API response contains a significant amount of data transforms may take some time to apply. Increasing the resources of the Server hosting Api2File can sometimes mitigate such increases in latency.

Core transformation concepts

Transforms utilise the Microsoft .net Razor templating engine. This enterprise grade technology powers millions of webpages worldwide and has a proven performance and reliability track record. Microsoft provide extensive Documentation on the Razor syntax, however, anyone familiar with the C# or Java syntax will find it quick and easy to achieve the required data shape using Razor templates.

Data provided by an API is read fully, parsed according to the Content-Type header (or override if specified), and made available to the transformation engine. The Razor templates can access the API data and modify it in any required manner, before outputting the transformed data, line by line, as a file for the end user.

Api2File provides three main ways of defining the lines that will make up the transformed file:

Static text

Static text can be used in a template where the output is fixed and known at design time. A common example is that of the header row in a CSV file.

Razor variables

In order to output dynamic content, based on API response content, or System data, a template can contain Razor variables (prefixed with @. These variables are replaced during transformation with the data values they represent.

Full code

Where a complex transformation of the API response data is required, c# code can be provided that will be executed at the time of transformation. Although involving the most complex syntax of the three Api2File ways of defining the template, it allows for complete customisation of the output data.

Configuring line templates

Transform templates are easily configured in the apis.yaml file. Once defined, they only require Api2File to be restarted for them to be applied to API data. No code compilation steps are required, meaning files can be edited in place using any readily available text editor, or the .yaml file can be version controlled and deployed using suitable SysOps tooling.

A transformation template comprises one or more Line definitions within the transform: block.

- share-name: weather-csv
  file-name: "london-temps.csv"
  target-api:
   ...
  transform:
    - line: "TemperatureC"
    - line: "------------------------------"
    - line: |
        @foreach(var tempC in Model.Content.GetItems(""){
          Write(tempC);
          Write(System.Environment.NewLine);
        }
    - line: "------------------------------"

    TemperatureC
    ------------------------------
    10.4
    11.7
    11.1
    ...
    8.0
    ------------------------------

Each Line block will automatically have a newline character appended to its end. However, in the case of multiple calls to Write() in a single Line block, a NewLine must also be outputted.

Text Blocks

As an alternative to the Write() command, content to be outputted that is nested within a code block, can utilise a <text></text> block.

  transform:
    - line: |
        @foreach(var tempC in Model.Content.GetItems(""){
          <text>@tempC@System.Environment.NewLine</text>
        }

Built-in functions

Api2File templates automatically have access to some helper functions. These provide ways to access the API Response data and headers.