Getting Started

Making a REST API call

The simplest way to get started is by making an actual API call. For example, to list all the services on your Gateway:

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/services

The above link makes a REST API call to list all the services in the Gateway.

The URL

All the available API calls have a similar URL format:

https://[gateway-host]/[restman-service]/[api-version]/[api-resource]

[gateway-host]Host and port of the Gateway.
[restman-service]Published URI of the REST management service. Default is "restman".
[api-version]Version of the API that you are accessing; all API calls require an API version. Current version is 1.0.
[api-resource]Resource being accessed. This can either map to an actual resource available on the Gateway, like a policy or JDBC connection, or it can reference an available service, like the migration service.

The Response

All API calls will return the results wrapped. The wrapper will be either a l7:List or l7:Item. These are both based on the same underlying object and so they both will have:

NameA human readable name describing the contents
TypeType of the item that this contains
TimeStampWhen this item was created
Link0 or more links relating to the containing object

The List wrapper will also contain 0 or more Items. These items are the listing results.

The Item wrapper will contain an ID element containing the ID of the contained object. The Item wrapper will also contain a single resource. This resource will be the object that this item wraps.

WADL and Schema

For more information on the REST Management API see the associated WADL and XSD schema:

WADL: $#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/rest.wadl

Schema: $#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/gateway-management.xsd

Setting Up

Set Up from the Policy Manager

To install the Gateway REST Management Service from the Policy Manager:

  1. Select Tasks -> Publish Internal Service from the main menu (on the browser client, from the Manage menu). The Publish Internal Service Wizard appears.
  2. Choose "Gateway REST Management Service" from the drop-down list as the service to publish.
  3. Optionally, change the routing URI if necessary. Note that the routing URI should always end with a "/*"
  4. Click [Finish] to publish the internal service. This will create a new service in the root folder called "Gateway REST Management Service".

Set Up Using Auto-Provisioning

The Gateway REST Management service can be installed automatically on a new Gateway using the auto-provisioning service.

A Gateway can automatically install an internal service on startup if it is licensed and there are no other services installed (as would be the case for a new Gateway). This is done by providing a file in a folder on the Gateway machine specifying the internal service to install. By default, running this command on the Gateway should set it up:

touch /opt/SecureSpan/Gateway/node/default/etc/bootstrap/services/restman

Basic Entity Operations

Most of the entities support the same set of similar operations. These include the basic CRUD (Create, Read, Update and Delete) operations, Listing/Searching operations, and retrieving template (example) entities. The general use case for these operations is described below.

Listing and Searching Entities

You can list all entities of a given type by making a GET request to that entity's URI. For example, to list all Folders on the Gateway, make a request to:

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders

Listing Example
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders
Http Method GET
Response
Http Status 200
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:List xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>FOLDER list</l7:Name>
    <l7:Type>List</l7:Type>
    <l7:TimeStamp>2014-04-24T15:27:30.386-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders"/>
    <l7:Link rel="template" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/template"/>
    <l7:Link rel="list" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders"/>
    <l7:Item>
        <l7:Name>Root Node</l7:Name>
        <l7:Id>0000000000000000ffffffffffffec76</l7:Id>
        <l7:Type>FOLDER</l7:Type>
        <l7:TimeStamp>2014-04-24T15:27:30.384-07:00</l7:TimeStamp>
        <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/0000000000000000ffffffffffffec76"/>
        <l7:Resource>
            <l7:Folder id="0000000000000000ffffffffffffec76" version="0">
                <l7:Name>Root Node</l7:Name>
            </l7:Folder>
        </l7:Resource>
    </l7:Item>
    <l7:Item>
        <l7:Name>My Services</l7:Name>
        <l7:Id>78457446b2cea4de5244873fe56a9f31</l7:Id>
        <l7:Type>FOLDER</l7:Type>
        <l7:TimeStamp>2014-04-24T15:27:30.385-07:00</l7:TimeStamp>
        <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/78457446b2cea4de5244873fe56a9f31"/>
        <l7:Resource>
            <l7:Folder folderId="0000000000000000ffffffffffffec76" id="78457446b2cea4de5244873fe56a9f31" version="0">
                <l7:Name>test</l7:Name>
            </l7:Folder>
        </l7:Resource>
    </l7:Item>
</l7:List>

The returned message above shows two folders:

The listing API call can also be used for searching and sorting entities. For example, many entities have a name and in most cases you can find an entity by its name using the listing API call and providing a name parameter. Specifically, you can find the folder named "My Services" using the following API call:

Listing Example 2
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders?name=My%20Services
Http Method GET
Response
Http Status 200
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:List xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>FOLDER list</l7:Name>
    <l7:Type>List</l7:Type>
    <l7:TimeStamp>2014-04-24T15:27:30.386-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders"/>
    <l7:Link rel="template" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/template"/>
    <l7:Link rel="list" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders"/>
    <l7:Item>
        <l7:Name>Root Node</l7:Name>
        <l7:Id>0000000000000000ffffffffffffec76</l7:Id>
        <l7:Type>FOLDER</l7:Type>
        <l7:TimeStamp>2014-04-24T15:27:30.384-07:00</l7:TimeStamp>
        <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/0000000000000000ffffffffffffec76"/>
        <l7:Resource>
            <l7:Folder id="0000000000000000ffffffffffffec76" version="0">
                <l7:Name>Root Node</l7:Name>
            </l7:Folder>
        </l7:Resource>
    </l7:Item>
</l7:List>

The returned message is very similar to the one returned when listing all folders, however only the folder with the name "My Services" is returned. You can specify multiple search parameters to create more complex searches. For example, to list all enabled Gateway connectors using the HTTP or FTP protocols:

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/ssgconnectors?enabled=true&protocol=HTTP&protocol=FTP

Listing results can also be sorted and ordered using the "sort" and "order" query parameters. Refer to the WADL or the Resources to find what you can sort and search by for an entity. For example, use this to sort all email listeners in descending order by their host name:

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/emailListeners?sort=host&order=desc

If the returned list does not contain any items, then none could be found with the specified search fields or you do not have the correct permissions to view the items. See $#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/doc/authentication.html for more information on authentication and permissions.

Retrieving an Entity

An individual entity can be returned by using its ID. For example you can retrieve the secure password with ID "b0f109679d51ca3d3be3f08a13052f72" by making the following API call:

Retrieving Example 1
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/passwords/b0f109679d51ca3d3be3f08a13052f72
Http Method GET
Response
Http Status 200
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>MySecurePassword</l7:Name>
    <l7:Id>b0f109679d51ca3d3be3f08a13052f72</l7:Id>
    <l7:Type>SECURE_PASSWORD</l7:Type>
    <l7:TimeStamp>2014-04-24T16:12:44.383-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/passwords/b0f109679d51ca3d3be3f08a13052f72"/>
    <l7:Link rel="template" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/passwords/template"/>
    <l7:Link rel="list" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/passwords"/>
    <l7:Resource>
        <l7:StoredPassword id="b0f109679d51ca3d3be3f08a13052f72" version="1">
            <l7:Name>MySecurePassword</l7:Name>
            <l7:Properties>
                <l7:Property key="usageFromVariable">
                    <l7:BooleanValue>true</l7:BooleanValue>
                </l7:Property>
                <l7:Property key="description">
                    <l7:StringValue></l7:StringValue>
                </l7:Property>
                <l7:Property key="lastUpdated">
                    <l7:DateValue>2014-04-24T16:12:22.960-07:00</l7:DateValue>
                </l7:Property>
                <l7:Property key="type">
                    <l7:StringValue>Password</l7:StringValue>
                </l7:Property>
            </l7:Properties>
        </l7:StoredPassword>
    </l7:Resource>
</l7:Item>

Creating an Entity

In order to create an entity, send a POST request, with message body containing the entity description, to the entity's uri. All properties that are not in the entity description will be set to null. The following example shows how to create a new folder.

Creating Example 1
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders
Http Method POST
Content-Type application/xml
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Folder xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management" folderId="0000000000000000ffffffffffffec76">
    <l7:Name>My New Folder</l7:Name>
</l7:Folder>
Response
Http Status 201
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>My New Folder</l7:Name>
    <l7:Id>b0f109679d51ca3d3be3f08a1305300c</l7:Id>
    <l7:Type>FOLDER</l7:Type>
    <l7:TimeStamp>2014-04-24T16:24:48.353-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/b0f109679d51ca3d3be3f08a1305300c"/>
    <l7:Link rel="template" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/template"/>
    <l7:Link rel="list" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders"/>
    <l7:Link rel="dependencies" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/f2b947580bc1fc646dda444f577d546c/dependencies"/>
    <l7:Link rel="parentFolder" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/0000000000000000ffffffffffffec76"/>
</l7:Item>

You can create an entity with a specific ID by using the PUT HTTP method. See below for more details.

Updating an Entity

In order to update an entity, send a PUT request with the entity description to the entity's uri. All properties that are not in the entity description will be set to null. For example, to update the folder created above and change its name:

Updating Example
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/b0f109679d51ca3d3be3f08a1305300c
Http Method PUT
Content-Type application/xml
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Folder xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management"
                    folderId="0000000000000000ffffffffffffec76"
                    id="b0f109679d51ca3d3be3f08a1305300c"
                    version="0">
     <l7:Name>My Policies</l7:Name>
</l7:Folder>
Response
Http Status 200
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>My Policies</l7:Name>
    <l7:Id>b0f109679d51ca3d3be3f08a1305300c</l7:Id>
    <l7:Type>FOLDER</l7:Type>
    <l7:TimeStamp>2014-04-24T16:31:05.844-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/b0f109679d51ca3d3be3f08a1305300c"/>
    <l7:Link rel="template" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/template"/>
    <l7:Link rel="list" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders"/>
    <l7:Link rel="dependencies" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/b0f109679d51ca3d3be3f08a1305300c/dependencies"/>
    <l7:Link rel="parentFolder" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/0000000000000000ffffffffffffec76"/>
</l7:Item>

You can create an entity with a specific ID by sending a PUT request to that entity's URI. For example, to create a folder with the ID "b0f109679d51ca3d3be3f08a130530bf", send the following request:

Creating Example 2
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/b0f109679d51ca3d3be3f08a130530bf
Http Method PUT
Content-Type application/xml
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Folder xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management" folderId="0000000000000000ffffffffffffec76" version="0">
     <l7:Name>My Encass Policies</l7:Name>
</l7:Folder>
Response
Http Status 201
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>My Encass Policies</l7:Name>
    <l7:Id>b0f109679d51ca3d3be3f08a130530bf</l7:Id>
    <l7:Type>FOLDER</l7:Type>
    <l7:TimeStamp>2014-04-24T16:34:48.521-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/b0f109679d51ca3d3be3f08a130530bf"/>
    <l7:Link rel="template" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/template"/>
    <l7:Link rel="list" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders"/>
    <l7:Link rel="dependencies" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/b0f109679d51ca3d3be3f08a130530bf/dependencies"/>
    <l7:Link rel="parentFolder" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/folders/0000000000000000ffffffffffffec76"/>
</l7:Item>

Note that when updating an entity, all properties of that entity must be specified, even those that are not changing, otherwise they will be set to null.

Deleting an Entity

An entity can be deleted by sending a DELETE request to that entity's URI. For example, to delete a policy with ID "b0f109679d51ca3d3be3f08a130531a0" send the following request:

Deleting Example
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/policies/b0f109679d51ca3d3be3f08a130531a0
Http Method DELETE
Response
Http Status 204

Retrieving an Entity Template

Most entities have a template uri that allows you to retrieve a template entity object. This can be used to then create a new entity. For example, the template for cluster properties can be retrieved as follows:

Template Example
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/clusterProperties/template
Http Method GET
Response
Http Status 200
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>CLUSTER_PROPERTY Template</l7:Name>
    <l7:Type>CLUSTER_PROPERTY</l7:Type>
    <l7:TimeStamp>2014-04-24T16:44:56.440-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/clusterProperties/template"/>
    <l7:Link rel="list" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/clusterProperties"/>
    <l7:Resource>
        <l7:ClusterProperty>
            <l7:Name>Template Cluster Property Name</l7:Name>
            <l7:Value>Template Cluster Property Value</l7:Value>
        </l7:ClusterProperty>
    </l7:Resource>
</l7:Item>

Other Operations

Dependency Analysis

Entities may depend on each other in many different ways. For example, a service may require a secure password and a JDBC connection.

You can view the dependencies for a service, folder, policy, or encapsulated assertion by using the dependency analysis sub-resource.

For example, to display all the dependencies for a service, make the following API call:

Dependency Example
Request
Uri
$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/services/b0f109679d51ca3d3be3f08a13053261/dependencies
Http Method GET
Response
Http Status 200
Message Body 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>MyService dependencies</l7:Name>
    <l7:Type>DEPENDENCY</l7:Type>
    <l7:TimeStamp>2014-04-24T16:59:14.373-07:00</l7:TimeStamp>
    <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/services/b0f109679d51ca3d3be3f08a13053261/dependencies"/>
    <l7:Resource>
        <l7:DependencyList>
            <l7:Reference>
                <l7:Name>LookupInDatabase</l7:Name>
                <l7:Id>b0f109679d51ca3d3be3f08a13053261</l7:Id>
                <l7:Type>SERVICE</l7:Type>
                <l7:Dependencies>
                    <l7:Dependency>
                        <l7:Name>jdbc1</l7:Name>
                        <l7:Id>08d65a5a4449f13594a9379d1bb3820d</l7:Id>
                        <l7:Type>JDBC_CONNECTION</l7:Type>
                    </l7:Dependency>
                </l7:Dependencies>
            </l7:Reference>
            <l7:Dependencies>
                <l7:Dependency>
                    <l7:Name>pass1</l7:Name>
                    <l7:Id>08d65a5a4449f13594a9379d1bb38215</l7:Id>
                    <l7:Type>SECURE_PASSWORD</l7:Type>
                </l7:Dependency>
                <l7:Dependency>
                    <l7:Name>jdbc1</l7:Name>
                    <l7:Id>08d65a5a4449f13594a9379d1bb3820d</l7:Id>
                    <l7:Type>JDBC_CONNECTION</l7:Type>
                    <l7:Dependencies>
                        <l7:Dependency>
                            <l7:Name>pass1</l7:Name>
                            <l7:Id>08d65a5a4449f13594a9379d1bb38215</l7:Id>
                            <l7:Type>SECURE_PASSWORD</l7:Type>
                        </l7:Dependency>
                    </l7:Dependencies>
                </l7:Dependency>
            </l7:Dependencies>
        </l7:DependencyList>
    </l7:Resource>
</l7:Item>

The Dependency list example above returns all the dependencies for the entity identified under "Reference". This reference contains:

NameHuman-readable name of the entity.
IdThe ID of the entity
TypeType of the entity
DependenciesA list of the direct dependencies for this entity

Following the Reference is a list of dependencies. This list includes all dependencies for the Reference, both direct and indirect. Each dependency contains:

NameHuman-readable name of the entity.
IdThe ID of the entity
TypeType of the entity
DependenciesA list of the direct dependencies for this entity

Migration

The Migration resource can be used to migrate folders, services, and policies between Gateways. For more information about using the Migration resource see:

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/doc/migration.html