Define the operations
In the previous topic, you created a 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 for the Airport-Data API A programming interface that defines how software can be interacted with by other software.. Now you will add an operation A single request to a third-party API. Operations often become actions in the workflow designer. to define an 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. for retrieving the airport information.
Summary
Operations are the functions calls available in the API, and are displayed as actions and events in the action group for this Xtension. Each operation you declare maps to an action in the action toolbox.
.
Note: You do not need to define every operation of the API within the OpenAPI Specification. Only define the operations you want to use.
Operations as paths and methods
Operations in the OpenAPI Specification are defined in two parts:
- 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. to access the operation or resource on the host
- The HTTP Hypertext Transfer Protocol: the protocol by which websites and APIs communicate over the internet. method to use when requesting the resource, such as GET or POST
Each combination of path and method creates a unique operation, but not all combinations are necessarily supported by the API. Operations must be defined to match the API exactly: you cannot substitute an HTTP method or change the path.
In the Workflow Designer, the actions are listed in the action toolbox in the order you define them.
Define the operations
To define an operation, you define:
- The path to the resource
- The HTTP method to access the resource
- The operation details, including a description of the operation and what format it returns
Step 1: Add the paths object
All operations in an OpenAPI Specification are enclosed within the paths object. The paths object is usually added after the basic OpenAPI Specification structure, but before the closing brace at the end of the file. Make sure you include the opening and closing braces of the object.
{
"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": {
}
}
Step 2: Add the operation path
Within the paths object, the resource path to access the operation is added as another object. In this example, the resource path is /ap_info.json. Note that the braces of the path object completely enclose the resource path object.
"paths": {
"/ap_info.json": {
}
}
Defining more than one path
If your API uses more than one path for its operations, create a path object for each path, and separate them with commas.
"paths": {
"/ap_info.json": {
},
"/ap_test.json": {
}
}
Step 3: Add the HTTP method
Within the resource path object, the HTTP method to use for this operation is added as another object. In this example, the method is get. Notice that the braces of the resource path object completely enclose the HTTP method object.
"paths": {
"/ap_info.json": {
"get": {
}
}
}
If your API uses more than one HTTP method with a path, create an HTTP method object for each method, and separate them with commas.
"paths": {
"/ap_info.json": {
"get": {
},
"post": {
}
},
}
Step 4: Add the operation details
Now that the operation path and method have been specified, add the details about this operation inside the HTTP method object:
- The summary is the name of the operation, and is used as the name of the action in the Workflow designer.
- The description is a brief explanation of what the operation does. This is for documentation purposes in the OpenAPI Specification only, and does not appear in your workflow.
- The operationId is a unique identifier for the operation within the OpenAPI Specification. This identifier must be unique for the OpenAPI Specification to be valid.
- The produces array defines the formats this API can return The return from a third-party API after a request has been made by the client. information in. It is included in case this operation overrides the global types provided in the basic OpenAPI Specification structure.
Note the comma after the closing square bracket of the produces array. This is required, because you will add more information to the HTTP method object in the next topic.
"paths": {
"/ap_info.json": {
"get": {
"summary": "Get airport info",
"description": "Get airport info",
"operationId": "getAirportInfo",
"produces": [
"application/json"
]
}
}
}
The OpenAPI Specification
The OpenAPI Specification now contains an operation that can be used as an action in the Workflow designer. Next you will add the parameters that the API needs to process the request.
{
"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"
]
}
}
}
}