Define the parameters
In the previous topic, you added an operation A single request to a third-party API. Operations often become actions in the workflow designer. to your basic OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. structure to retrieve information about an airport. Now you will add a parameter A piece of information passed to a third-party API during a request. to pass the airport code of the airport that you want to retrieve information on. This parameter appears as a configuration field for the action A task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality. in the Workflow designer.
Tip: Want the short version? Check out our OpenAPI Specification quick reference for quick definitions of parameter types, authentication, file handling and Specification Extensions.
Summary
A parameter is a piece of information required by the API A programming interface that defines how software can be interacted with by other software. in order to complete the operation. Parameters can be passed to operations in several locations:
- Appended to the URL as a query Part of the URL that does not fit into the path structure, and provides additional information or parameters for the request. The query is prefaced by a question mark (?) in the URL, for example: http://example.com?color=blue.
- Included in the URL as part of the path The part of the URL after the hostname that directs the request to a specific resources within the host. For example, the section after "example.com" in http://example.com/this/is/a/path.
- Passed in the header The section of the HTTP request that defines the operation of the request, including authorization. of the HTML
- Passed in the body The part of an HTTP request or response that can contain an arbitrary amount of data, such as the content of a form or web page. of the HTML
- Passed as the content of a form
In this example, you will define one parameter to be appended to the URL as a query. For instructions on defining multiple parameters, see Defining more than one parameter. For examples on how to pass parameters by other methods, see Alternative parameter locations.
Parameters in the OpenAPI Specification
Parameters for each operation are defined in the parameters array within the HTTP method object. Each parameter must have a unique name within the location it is passed in for the OpenAPI Specification to be valid. For example, you could have two parameters with the name of ID if one were passed in the query, and the other in the body, but not if both parameters were passed in the query.
Parameters must be defined as they appear in the API. If the API requires the parameter in a query, your OpenAPI Specification must define the parameter as being passed in the query.
Define the parameters
To define a parameter, you define:
- The name of the parameter
- The data type of the parameter
- The location in which the parameter is passed
Step 1: Add the parameters array
Each operation in an OpenAPI Specification defines its own array of parameters within the HTTP method object. The parameters array is usually added after the produces array, before the closing brace of the HTTP method object.
"get": {
"summary": "Get airport info",
"description": "Get airport info",
"operationId": "getAirportInfo",
"produces": [
"application/json"
],
"parameters": [
]
}
Step 2: Add a parameter object
Each parameter is defined as an object within the parameters array, with each parameter object having multiple key : value pairs. Add an open and closing brace to create an empty object within the parameters array to hold the parameter.
"parameters": [
{
}
]
Defining more than one parameter
If you need to define more than one parameter, create an object for each parameter within the array's square brackets and separate the objects with commas.
"parameters": [
{
"name": "p1"
},
{
"name": "p2"
}
]
Step 3: Add the parameter name and type
Parameters must have a name and a data type, such as string (text) or number.
"parameters": [
{
"name": "iata",
"type": "string"
}
]
Nintex Automation Cloud uses the name and type to create the configuration field for this action in the Workflow designer.
Step 4: Add the parameter location
Parameters must have a location, which specifies how they are passed to the API. The location is defined with the key in. Passing the parameter in the query appends it to the API URL.
"parameters": [
{
"name": "iata",
"type": "string",
"in": "query"
}
]
Alternative parameter locations
Passing the parameter in the header
Passing a parameter in the header means it is inserted into custom headers with the request. To pass a parameter in the header, create the parameter object and define the location with the value of header.
"parameters": [
{
"name": "iata",
"type": "string",
"in": "header"
}
]
Passing a parameter in the path means it is inserted in the URL. For example, www.airport-data.com/api/ID, where ID is the parameter being passed.
To ensure the parameter is inserted into the correct location in the URL, the path object is defined with placeholders that identify the parameters by their name.
To pass a parameter in the path:
- Define your parameter objects using the steps in this topic.
- Add the property "required": true to the definition of every parameter included in the path.
- Define the location of your parameter with the value of path
- Add the placeholders to the path definition by wrapping the parameter name in braces
Note: Make sure the path lists the parameters in the order required by the API.
"paths": {
"/ap_info.json/{airportCode}": {
"get": {
"summary": "Get airport info",
"operationId": "getAirportInfo",
"produces": [
"application/json"
],
"parameters": [
{
"name": "airportCode",
"type": "string",
"required": true,
"in": "path"
}
]
}
}
}
Passing a parameter in the body means it is passed in the body of the HTTP request. Only one parameter can be passed in the body. Parameters passed in the body must be defined by a schema object.
To pass a parameter in the body:
- Define your parameter objects using the steps in this topic.
- Define the location of your parameter with the value of body
- Instead of the parameter type, create a schema object.
- Add a properties object to the schema object.
- Create each property as an object with the property's name as the key.
- Inside each property object, add the property data type.
- Add a required array at the top of the schema object with the names of the properties that must be passed to the API for the operation to function.
"parameters": [
{
"name": "airportCode",
"in": "body",
"schema": {
"required": [
"code"
],
"properties": {
"code": {
"type": "string"
}
}
}
}
]
Step 5: Add watermark text
You can guide designers with watermark or placeholder text when they configure your custom actions. Nintex Automation Cloud uses the description key in the parameter object to create watermark text in the configuration field for the action.
Note: Watermark text is not displayed for enum parameters, or other drop-down list configuration fields.
"parameters": [
{
"name": "iata",
"type": "string",
"in": "query",
"description": "Airport code"
}
]
The OpenAPI Specification
The OpenAPI Specification now defines the operations you can perform, and the parameters needed for those operations. Next you will describe the response the API will return when the operation is called.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Airport Data",
"description": "Retrieves location information based on airport codes"
},
"host": "www.airport-data.com",
"basePath": "/api",
"schemes": [
"https"
],
"produces": [
"application/json"
],
"paths": {
"/ap_info.json": {
"get": {
"summary": "Get airport info",
"description": "Get airport info",
"operationId": "getAirportInfo",
"produces": [
"application/json"
],
"parameters": [
{
"name": "iata",
"type": "string",
"in": "query",
"description": "Airport code"
}
]
}
}
}
}