REST Swagger File Reference Format

The descriptor for a REST service is a JSON file that contains information about the API and its data structure. The K2 REST broker uses this descriptor to communicate with the REST service, whether that's a service you own or one available on the Internet. This JSON file may be referenced either as a local file or an HTTP URL.

There are different ways to get a Swagger file for using with the REST broker, listed here in order of recommendation:

1. Use the Swashbuckle package to generate a Swagger descriptor file. See https://community.nintex.com/k2-blackpearl-38/how-to-generate-a-swagger-descriptor-for-rest-based-services-using-swashbuckle-28534 for details on how to do this. This is the recommended approach if you own the API and can modify the source code.
2. Ask the person who owns the API to generate a Swagger file for you.
3. Use RESTUnited to generate a Swagger file based on the payload of the service. See https://community.nintex.com/k2-blackpearl-38/generating-a-swagger-descriptor-for-rest-based-services-using-restunited-com-28535 for details on how to do this. This is the recommended approach if you do NOT own the API. However, this approach typically requires that you to edit the Swagger descriptor to flatten entities.
4. Generate a Swagger file manually. This is the least desirable approach as it requires extensive knowledge of the Swagger schema for the REST broker, JSON formatting, and knowledge of the API. However, this approach remains feasible if it is your only option. It is best to start with known Swagger descriptor files. See https://community.nintex.com/automation-on-prem-43/resources-for-working-with-the-rest-service-broker-93 for more information.

The REST broker supports portions of the Swagger v2 specification. For details about which elements are supported, see the Swagger Support Matrix.

Anatomy of a Swagger file

Paths

The paths portion of a Swagger file describes the URL paths, relative to the host and basePath previously defined, that the service provides. The path string may include path template tokens, which will be replaced with parameter values as described below.

1
2
3
4
5
6
7
"/pets" : {
    "get": { ... },
    "post": { ... },
},
"/order/{id}" : {
    "get": { ... },
}

Each path contains one or more operation nodes. An operation represents an HTTP verb or action. Swagger 2.0 supports seven operations; the current version of the REST Broker supports the following five:

1
2
3
4
5
"get": { ... },
"post": { ... },
"put": { ... },
"delete": { ... },
"patch": { ... },

Each path can define only one of each operation type. For example, a path cannot define two get operations. If you are describing a service that exposes two GET calls for the same path try appending an extraneous query parameter to make Swagger see it as a different path:

1
2
3
4
5
6
"/pets" : {
    "get": { ... },
},
"/pets?brokerWorkaround=ignoreMe" : {
    "get": { ... },
},

OperationId (method name)

By convention, the operationId property is used to provide a friendly name for the operation. The REST Broker uses this value for the Method name. If no operationId is provided in the descriptor, the broker will attempt to construct a method name from the path and operation type (e.g. get, post, delete)

1
2
3
4
5
6
7
8
"paths": {
    "/customers": {
        "get": {
            "operationId": "GetAllCustomers",
            ...,
        },
    }
}

Parameters

In Swagger, the body of the HTTP request and headers as well as form, query and URL parameters are all described as parameters of the operation:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "in": "path",
    "name": "id",
    "required": true,
    "type": "integer"
},
{
    "in": "body",
    "name": "body",
    "required": true,
    "schema": { "$ref": "#/definitions/Pet" }
}

The type of parameter is noted by the in property, which can be any of the following:

• path
• query
• body
• file
• header

The current version of the REST Broker supports all of these EXCEPT header.

The first example above defines a parameter that is passed as part of the path itself. A path template token with the same name is expected to be in the path definition:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"paths": {
    "/order/{id}" : {
        "get": {
            "parameters": [
                {
                    "in": "path",
                    "name": "id",
                    "required": true,
                    "type": "integer"
                }
            ]
        }
    }
}

The same technique can be used for query parameters. Body parameters define the contents of the main body of the HTTP request. File parameters are described below.

A few rules about parameters (for more, see the Swagger documentation on parameters):

• Parameters in path MUST be required.
• Parameters in body MUST provide a value for schema. (Other parameters MUST define a type.)
• The "header" value for in is not currently supported by the REST Broker.

File Parameters

Swagger only supports describing file uploads using a multi-part form POST. For detailed information, see the Swagger documentation on parameters. For information about getting files from a service, see Handling Files in the Response

The following example outlines the basics for defining a file upload parameter:

1
2
3
4
5
6
7
8
9
10
11
12
13
"get": {
    "consumes": [
        "application/x-www-form-urlencoded"
    ],
    "parameters": [
        {
            "in": "formData",
            "name": "file",
            "required": true,
            "type": "file"
        }
    ]
}

The rules for file parameters are as follows:

• MUST be in formData
• consumes MUST be one of the following values:
  • application/x-www-form-urlencoded
  • multipart/form-data

Responses

Each Swagger operation MUST include at least one response definition, and should include the response for a successful call. Each response consists of the relevant HTTP Status Code - or the keyword default - and the defining Response Object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"post": {
    ...,
    "responses": {
        "201": {
            "description": "Customer created (ID returned)",
            "schema": { "type": "integer" }
        },
        "400": {
            "description": "Invalid Customer data"
        },
        "default": {
            "description": "Unexpected error (detail included)",
            "schema": { "type": "string" }
        }
    }
}

The REST Broker determines what it considers to be the "success" response - the response it expects to receive from the operation - using the following logic:

• The lowest 2xx HTTP Status Code present.1.
• The default response, if present.2.
• The first response in the list.3.
• If no responses are found, the broker will not expect a response value from the operation.

Any other response that occurs is handled as an error.

Definitions

All complex entities used or returned by the API should be defined in the Swagger definitions section. The REST Broker creates a SmartObject for each entity described.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
"definitions" : {
    "Customer": {
        properties: {
            "ID": { "type": "integer" },
            "Active": { "type": "boolean" },
            ...
        }
    },
    "Order": {
        properties: {
            "ID": { "type": "number" },
            "Customer": {
                "$ref": "#/definitions/Customer"
            },
            "Date": {
                "type": "string",
                "format": "date-time"
            },
            ...
        },
    },
}

Each entity is defined by its name (i.e. "Customer" highlighted above) followed by a JSON Schema object.

Handling Files in the Response

If the service you are calling returns a file (such as a PDF or Word document), you cannot directly map the returned file to a SmartObject property of type “File”. Instead, any unsupported or unrecognized type is mapped to a SmartObject property of type “Object” (Memo behind the scene), and then you can use the Get File from Content inline function to decode the file contents.

K2 Swagger Extensions

In order to integrate smoothly with K2 technologies the REST Broker recognizes the following extensions to the Swagger specification:

1
2
3
4
5
6
7
8
9
"userTypeCustomer": {
    "properties": {
        "Name": {
            "schema": { "type": "string" }
        },
        ...
    },
    "x-k2-displayName": "User (Customer)"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"paths": {
    "/orders?for={id}": {
        "get": {
            "operationId": "CustomerOrders",
            ...,
            "x-k2-entityName": "Customer"
        },
    }
},
"definitions": {
    "Customer": {
    ...
    }
}

Resolving Validation or Namespace Errors

If you see validation or namespace errors when trying to register your instance, it may mean that the Swagger file defintions section contains nested objects. The REST broker does not work with nested complex entities of the object type. For example, the category of the Pet object references the definition of category:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
"Pet" : {
    "type" : "object",
    "required" : ["name", "photoUrls"],
    "properties" : {
        "id" : {
            "type" : "integer",
            "format" : "int64"
        },
        "category" : {
            "$ref" : "#/definitions/Category"
        },
        "name" : {
            "type" : "string",
        },
        ...

The category entity is defined separately (as a sibling of Pet) as its own object. Simple types are properties of an object, but object types must be defined separately and referenced.

1
2
3
4
5
6
7
"Category" : {
    "type" : "object",
    "properties" : {
        "id" : {
            "type" : "integer",
            "format" : "int64"
            ...

Dynamic Bindings

The REST broker supports static constructs, which means that if the objects returned by the service vary from call to call, the REST broker cannot work with those objects.

Dynamic API URI bindings: Some services implement load balancing by requiring a call to establish a session and, as a result of that call, you get a base URI to be used for all subsequent calls. Salesforce and Eloqua are examples of these services. The Swagger spec partially supports this construct at the time of publication but it isn’t defined enough for the REST broker to work with.

Dynamic Property Name bindings: Some services implement dynamic property names, where calls to the same endpoint result in the same payload structure but the names of the properties change with every call. The Swagger spec partially supports this construct at the time of publication but it isn’t defined enough for the REST broker to work with.

When to Use a Root Object

Sometimes it is necessary to create a root object to hold the contents of the returned objects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "result": [
        {
            "sys_name": "SLA Repair Log Entry0004",
            "sys_class_name": "sys_db_object"
        },
        {
            "sys_name": "Dscy Priv Command Affinity",
            "sys_class_name": "sys_db_object"
        },
        {
            "sys_name": "Sys Plugins",
            "sys_class_name": "sys_db_object"
        },
        {
            "sys_name": "Alm Fixed Assets",
            "sys_class_name": "sys_db_object"
        },
        {
            "sys_name": "CMDB CI Server",
            "sys_class_name": "sys_db_object"
        }
    ]
}

The result object is not an array but it contains an array of strings. Creating a root object is necessary for the service to serialize and deserialize properly. To do this, first create an entity called rootObject that includes a reference to your result object and is an array object, as follows:

1
2
3
4
5
6
7
8
9
10
11
"rootObject": {
    "type": "object",
    "properties": {
        "result": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/result"
            }
        }
    }
},

Use a reference to this rootObject in your method response, as follows:

1
2
3
4
5
6
7
8
"responses": {
    "200": {
        "description": "OK",
        "schema": {
            "$ref": "#/definitions/rootObject"
        }
    }
}

Finally, for your result object, specify the properties of type string that are parsed from the array:

1
2
3
4
5
6
7
8
9
10
11
12
"result": {
    "type":"object",
    "description": "Model for Result",
    "properties": {
        "sys_class_name": {
            "type": "string"
        },
        "sys_name": {
            "type": "string"
        }
    }
}