Define the responses
In the previous topic, you added a parameter A piece of information passed to a third-party API during a request. to your operation A single request to a third-party API. Operations often become actions in the workflow designer., to send the airport code to the Airport-Data API in order to retrieve information about that airport. Now you will define the response you expect from the API A programming interface that defines how software can be interacted with by other software., including the format of the returned data. The returned data structure appears as configuration fields for this 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.
Summary
A response The return from a third-party API after a request has been made by the client. is a reply from the API to a specific operation. It includes the HTTP Hypertext Transfer Protocol: the protocol by which websites and APIs communicate over the internet. status code, and a definition of any returned data.
Responses in the OpenAPI Specification
Responses are defined in the responses object within each operation. You must use the status codes and variable names defined by the API.
Some APIs return a lot of data in their response. To avoid cluttering the Workflow designer configuration screens with fields, only define the data you plan to use. Anything you do not define will not be available to you in the Workflow designer.
Define the responses
To define a response, you define:
- The HTTP status code that identifies the response.
- The description of the response. This is for documentation purposes only within the OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger., and does not appear in the workflow.
- The definition of any data delivered by the response.
Step 1: Create the responses object
Each operation in an OpenAPI Specification defines its own responses object within the HTTP method object. The responses object is usually added after the parameters 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": [
{
"name": "iata",
"description": "Airport code",
"in": "query",
"type": "string"
}
],
"responses": {
}
}
Step 2: Create a response
Each response is defined as an object, with a key of the HTTP status code returned by the API. Add an opening and closing brace to hold the definition of the response.
"responses": {
"200": {
}
}
Defining more than one response
If you want to make use of more than one response that the API provides, create a response object for each and separate them with commas.
"responses": {
"200": {
},
"204": {
}
}
Step 3: Describe the response
Add a description to help anyone reading the OpenAPI Specification understand what the response is used for, and a schema object that defines the type of response as an object.
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
}
}
Step 4: Define the response data
Create a properties object to define the data returned. Inside the properties object, list each return variable as an object with the variable's name as the key, and the data type of the variable inside.
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"location": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
}
Nintex Automation Cloud uses the properties to create the Result configuration fields for this action in the Workflow designer.
The OpenAPI Specification
The OpenAPI Specification is complete. You could import this OpenAPI Specification as-is and use it in your workflows. But using references can make building and maintaining your OpenAPI Specification much easier. Next, you will add a reference to the response schema to the OpenAPI Specification.
{
"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",
"description": "Airport code",
"type": "string",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"location": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
}
}
}
}
}