Building request parameters & request body for an OpenAPI request

Knowledge base
,
1

webMethods Integration Server version: 10.7 and above

What are the supported Request parameters in an OpenAPI Request?

Following are the supported parameters:

  1. Path Parameters
  2. Query Parameters
  3. Header Parameters
  4. Cookie Parameters

The parameter format depends on the style and the explode attributes defined for the parameter in an OpenAPI document. Complex structures like JSON or XML can also be defined for the above parameters.

Use cases

How to build PATH Parameter for an OpenAPI Request?

Path parameters are serialized in three styles, matrix, simple, and label.
Semantics for the parameter may vary based on the schema type and value defined for the explode attribute in the parameter definition.

Note:
It is highly recommended to percent-encode any special characters in the parameter value.

Pre-Conditions

  1. The user has an OpenAPI document from the service provider.
  2. The OpenAPI document must have an API with a path parameter.

Basic Flow

  1. From the OpenAPI document, identify the API to be invoked.
  2. If the API defines a path parameter, select the parameter name.
  3. Check the style and the exploded attributes defined for the parameter.
  4. Format the parameter as described in the following table:
Style Explode Primitive Type Array Type Object Type
Matrix false ;color=blue ;color=blue,red,green ;color=R,100,G,200,B,150
true ;color=blue ;color=blue;color=red;color=green ;R=100;G=200;B=150
Label false .blue .blue.red.green .R.100.G.200.B.150
true .blue .blue.red.green .R=100.G=200.B=150
Simple false blue blue,red,green R,100,G,200,B,150
true Blue Blue,red,green R=100,G=200,B=150
  1. Add the formatted parameter to the API request URL.

Example Definition
image

Example URL
https://editor.swagger.io/api/v3/path/simple/explode-true/available/1,2/idname=string,idvalue=0

How to Build QUERY Parameter for an OpenAPI Request?

Query parameters are serialized in four styles, form, spaceDelimitted, pipeDelimitted, and deepObject.

Semantics for the parameter may vary based on the schema type and the value defined for the explode attribute in the parameter definition.

Note:
It is highly recommended to percent-encode any special character in the parameter value.

Pre-Conditions

  1. User is provided with an OpenAPI document from the service provider.
  2. The OpenAPI document has an API with a query parameter.

Basic Flow

  1. From the OpenAPI document, identify the API to be invoked.
  2. If the API defines a query parameter, select the parameter name.
  3. Check the style and the explode attributes defined for the parameter.
  4. Format the parameters as described in the following table:
Style Explode Primitive Type Array Type Object Type
form false color=blue color=blue,red,green color=R,100,G,200,B,150
true color=blue color=blue&color=red&color=green ;R=100&G=200&B=150
spaceDelimitted false NA Blue%20red%20Green R%20100%20G%20200%20B%20150
true NA NA NA
pipeDelimitted false blue Blue red
true NA NA NA
deepObject false NA NA Color[R]=100&Color[G]=200
&Color[B]=150
  1. Add the formatted parameter to the API request URL

Example Definition
image

Example URL
https://editor.swagger.io/api/v3/query/form/explode-true?id=1&idname=string&idvalue=0&idArr=param1&idArr=param2

How to Build HEADER Parameter for an OpenAPI Request?

Header parameters follow the “simple” style format.

Semantics for the parameter may vary based on the schema type and the value defined for the explode attribute in the parameter definition.

Pre-Conditions

  1. User is provided with an OpenAPI document from the service provider.
  2. The OpenAPI document has an API with a header parameter.

Basic Flow

  1. From the OpenAPI document, identify the API to be invoked.
  2. If the API defines a header parameter, select the parameter name.
  3. Check the style and the explode attributes defined for the parameter.
  4. Format the parameter as described in the following:
Style Explode Primitive Type Array Type Object Type
Simple false blue blue,red,green R,100,G,200,B,150
true Blue Blue,red,green R=100,G=200,B=150
  1. Add the formatted parameter to the API request URL.

Example Definition
image

Example Curl URL

curl -X 'GET' \
  'https://editor.swagger.io/api/v3/header/explode-true' \
  -H 'accept: application/json' \
  -H 'id: available' \
  -H 'idArr: 1,2' \
  -H 'idObj: idname=string,idvalue=0'

How to Build Cookie Parameter for an OpenAPI Request?

Cookie parameters follow the “form” style format.

Semantics for the parameter may vary based on the schema type and the value defined for the explode attribute in the parameter definition.

Pre-Conditions

  1. User is provided with an OpenAPI document from the service provider.
  2. The OpenAPI document has an API with a cookie parameter.

Basic Flow

  1. From the OpenAPI document, identify the API to be invoked.
  2. If the API defines a cookie parameter, select the parameter name.
  3. Check the style and the explode attributes defined for the parameter.
  4. Format the parameter as described in the following table:
Style Explode Primitive Type Array Type Object Type
form false color=blue color=blue,red,green color=R,100,G,200,B,150
true color=blue color=blue&color=red&color=green R=100&G=200&B=150
  1. Add the formatted parameter to the API request URL.

Example Definition
image

Example Curl URL

curl -X 'GET' \
  'https://editor.swagger.io/api/v3/cookie/explode-true' \
  -H 'accept: application/json' \
  -H 'Cookie: idname=string&idvalue=0'

How to Build complex Object Parameter for an OpenAPI Request?

OpenAPI Specification allows you to send more complex objects as values for all types of parameters it supports.

These complex objects are built using a particular MediaType format. For example, application/xml and application/json.

Integration Server supports only the following media types:

  • application/json
  • application/xml
  • text/xml
  • text/plain

Pre-Conditions

  1. User is provided with an OpenAPI document from Service Provider.
  2. The OpenAPI document has an API with a parameter defined with content.

Basic Flow

  1. From the OpenAPI document, identify the API to be invoked.
  2. If the API defines the content, select the media type of the parameter.
  3. Get the schema for the content defined and build the data in the format defined by MediaType .

For example,
image

image

  1. Add the formatted value against the parameter in the API request URL.

How to build request Body for an OpenAPI Request?

The OpenAPI provider defines the request body for an API. The body parameters are defined by the content attribute with one or more media type.

webMethods Integration Server supports only the following media types:

  • application/json
  • application/xml
  • text/xml
  • text/plain

Pre-Conditions

  1. User is provided with an OpenAPI document from Service Provider.
  2. The OpenAPI document has an API with a request body.

Basic Flow

  1. From the OpenAPI document, identify the API to be invoked.
  2. If the API defines the content, select the media type of the request.
  3. Get the schema definition for the media type selected.
  4. If the chosen mediaType is “application/xml”, ensure that the XML data is built with a single root element. Without a single root element, the XML structure is considered as invalid.
  5. For the XML structures, OpenAPI Specification defines the “XML” element for the schema. If the XML element defines the name attribute, ensure that the root element has the same name as the name attribute.
  6. To build the correct and compatible request payload structure, it is recommended to use the Swagger editor. The Swagger editor generates the example structure of each media type for every API that expects a request body.

For example,
image

image

  1. Add the formatted data to the request body.

References

OpenAPI Specification - Version 3.0.2 | Swagger

REST Capabilities In Integration Server - Knowledge base - Software AG Tech Community & Forums

Service Development Help | 10.7 | About JSON Document Types

1 Like