APIIDA API Gateway Manager

Service Templates

Service templates allow you to create starters for new services. Most services you will deploy on your gateway share boilerplate code that is almost the same throughout the board. Using the API Gateway Manager you can create templates that contain common fragments and have variables that can be replaced upon deploying new services based on this template. To make the template more versatile you can define blocks of assertion that are included or excluded based on choices presented to the user during service creation.

Template Parts

Templates consist of two parts. One part is a JSON file that describes the template and all of the variables and blocks that are contained in it. The second part is a XML file containing the policy for the new service.

Definition descriptions

XML Policy Definition

How to get the policy XML

To get the policy XML you can either export a existing service using the Policy Manager or you can just select the assertions you would like to include and use Copy & Paste to insert the XML code into the form or editor you use.

JSON Definition

First, let’s look at an example and then break it down:

{ "$schema": "https://apiida.com/schemas/layer7-template", "$version": "1.0", "name": "Basic template example", "description": "This is a basic template to demo service templates", "blocks": [ { "name": "useSSL", "description": "This API will only be available via SSL / https", "group": "Authentication" }, { "name": "auth", "description": "Means of authentication", "options": [ { "value": "basic", "text": "http Basic Authentication" }, { "value": "cert", "text": "Client Certificate" } ], "group": "Authentication" }, { "name": "validateBackendResults", "description": "Validate backend results against the Swagger-File" } ], "variables": [ { "name": "comment", "description": "This value is inserted into the policy", "type": "string", "required": true }, { "name": "date", "description": "Example for another datatype", "type": "date", "required": true, "group": "Authentication" }, { "name": "someElement", "description": "Select something", "type": "select", "required": false, "options": [ { "value": "A", "text": "This inserts A" }, { "value": "B", "text": "This inserts B" } ] } ] }

Variables, Blocks and Groups

Variables are replaced by what a user enters during creation of services that are based on the template. Blocks are parts within a policy that are either included in the resulting service or that are removed from its definition.

As you may have noticed you can assign a group to variables and blocks. This can be used to group settings that have a common theme. WIthin a group the blocks and variables are ordered the same way they are in the JSON definition.

Data Types

Type

Description

Type

Description

string

This datatype acts like a normal string. Please be advised that its inserted as it is. Which means that no base64 transformation happens. This datatype is not allowed to contain XML or HTML.

integer

A number without a fractional component (i.e. 5)

float

A number with a fractional component (i.e. 5.25)

date

A date value without time information

time

A time (formatted according to the format defined in the configuration)

datetime

A date value with time information

rawstring

In contrast to the string data type, this type allows any string, including XML or HTML.

select

A list of options. The value that is inserted and the text that is shown can be different from each other.

Modifiers

Modifiers define additional constraints for the entered values.

Modifier

Description

Modifier

Description

required

true / false. If a variable is declared to be required it will not be possible to create a new service if no value is entered in the variable.

XML Policy Definition with placeholders to work with JSON Definition

Variables are inserted by encapsulating them in double braces like {{variable}}. Blocks use a similar syntax but are defined within XML comments, so that the template still is a valid XML document. If your block is a select block, that is one that inserts different markup based on a selection it has the form of {{blockname=value}}.

The format for a block is:

<!-- {{myBlock}} --> <... logic to include if myBlock is selected ...> <!-- {{/myBlock}} --> <!-- {{myBlockA=choice1}} --> <... logic to include if choice1 is selected ...> <!-- {{/myBlockA}} --> <!-- {{myBlockA=choice2}} --> <... logic to include if choice2 is selected ...> <!-- {{/myBlockA}} --> <L7p:Comment stringValue="{{someElement}}"/>

 

Basic example:

XML Policy Definition

How to get the policy XML

To get the policy XML you can either export a existing service using the Policy Manager or you can just select the assertions you would like to include and use Copy & Paste to insert the XML code into the form or editor you use.

In this example, we created a very basic policy with four (4) comments.

Which copied and pasted in a text editor would give you the following.

This herebelow is not to be copied into the templates, it is an example of an export from the Policy Manager and needs to be edited to add the placeholders and triggers, see two sections below:

<wsp:Policy xmlns:L7p="http://www.layer7tech.com/ws/policy" xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy"> <wsp:All wsp:Usage="Required"> <L7p:CommentAssertion> <L7p:Comment stringValue="some comment"/> </L7p:CommentAssertion> <L7p:CommentAssertion> <L7p:Comment stringValue="SSL"/> </L7p:CommentAssertion> <L7p:CommentAssertion> <L7p:Comment stringValue="Auth BASIC"/> </L7p:CommentAssertion> <L7p:CommentAssertion> <L7p:Comment stringValue="Auth CERT"/> </L7p:CommentAssertion> </wsp:All> </wsp:Policy>

JSON Definition

Here is the example again, Copy and paste it under the Template tab:

XML Policy Definition with placeholders to work with JSON Definition

This is the edited XML that will work with the definition above Copy and paste it under the XML tab: :

In AAGM

XML Template example

This is what it would look like in AAGM, navigate to Templates → New Templates and copy/paste the above logics.

  1. These are variables, those will be substituted with the values that you set for them in the template GUI

  2. This enclosure makes sure that the inside XML block will be published in the logic on the Gateway only if the user will choose that variable in the GUI

  3. This is an if-else case, were one can choose the logic to include from a dropdown.

 

JSON Template example

  1. Determines the group, this is to group together functionalities in the GUI

  2. This is the option that relates to point 2 in the section above (the XML)

  3. This is the options list that relates point 3 in the section above (the XML)

  1. An example of how to request a variable input that is a string on the GUI, that will be then inserted in the placeholder described in step 1 in the ‘XML Template example’ section.

  2. An example of how to request a variable input that is going to trigger a calendar selection on the GUI, that will be then inserted in the placeholder described in step 1 in the ‘XML Template example’ section.
    Note: a Group name has been defined, which means that the Date field will appear in the Authentication group.

  3. An example of how to add a dropdown with given choices in the GUI, from which users need to choose allowing for set values and not openended as the steps hereabove, that will be then inserted in the placeholder described in step 1 in the ‘XML Template example’ section.

Result

Once saved here is the entry

Clicking now on Deploy (1) you will get the following screen

  1. Just some general information about the service to be deployed, this is not controlled by the JSON in the Template but is a standard form.

  2. That is the group that was defined in the example above.

  3. Any non-grouped components are listed in the Settings part, which is a sort-of Else grouping.

Push to Gateway

With the listed choices, the API is now pushed and here it is in the Gateway:

As mentioned, here is the service on the target:

  1. The name is the chosen one.

  2. The URL Path is also the right one.

  3. The Methods (or Verbs) are also the ones chosen.

  4. The SSL comment is shown as selected.

  5. The Basic Auth is shown as selected from the dropdown.

  6. The variables are all rewritten with the choices made in the GUI.