Lightweight Gateway API assembly commands and policies

execute command

The execute command provides a list of actions to be run, which can be interrupted if a particular action throws an error. The execute command supports the following policies:

invoke

Calls to a backend by using the provided target_url as its location. For this preview, invoke supports the following parameters:

• targetUrl - the URL for the target service
• verb - the HTTP method to use for the Invoke; the default value is KEEP
• tlsClientProfile - the TLS profile to use for the secure transmission of data
• input - the name of a message that will be used to form the request
• output - the name of a message that will be used to store the response data from the request
• timeout - the time (in seconds) to wait for a reply from the endpoint; the default value is 60

parse

Controls the parsing of a document. When the document is a JSON string, the string is parsed instead of copied over. If input parsing is desired, use the message name request; for the document that is returned from an invoke, use response as the message name. For this preview, parse supports the following parameters:

• input - the name of the input message in the API context
• output - the name of the output message in the API context
• documentType - the type of document being parsed in the API context
• maxDocumentSize - the maximum document size in bytes
• maxDepth - the maximum level of nested label-value pairs, the maximum number of nested arrays, or the maximum number of combination of label-value pairs and arrays
• maxWidth - the maximum number of properties on a JSON object or the maximum number of JSON items in a JSON array
• maxNameLength - the length of the label portion of the JSON label-value pair
• maxValueLength - the length of a string value
• maxNumberLength - the maximum number length in bytes in the value portion of a JSON label-value pair when the value is a number
• maxUniqueNames - the number is for unique JSON labels

rateLimit

Applies one or more rate limits at any point in your API assembly flow. Rate limits restrict the number of calls that are made to an API in a specified time period. Rate limits can also be configured to limit calls to other resources, such as a backend server. For this preview, rateLimit supports the following parameters:

• name - a text label for the rate limit
• intervalUnit - the unit of time used to describe the interval: second, minute, hour, or day
• intervalLen - the length of time (the number of units) during which the rate limit is applied
• max - the maximum number of calls allowed during the interval

set

Set the value of a runtime variable (including adding it) of a specified type by using the specified name and value. For this preview, set supports the following parameters:

• variable
  • name: string - name of variable
  • value: string - value of the variable to write
• messageBody
  • messageName: string - name of message to write value to.
  • value: string - value of body to write.
• messageHeader
  • messageName: string - name of message to write value to.
  • headerName: string - header name within the message to write.
  • value: string - value of header to write.

switch

Runs one of various sections of the assembly, based on which specified condition is fulfilled. A switch contains one or more of case objects; each case specifies one or more conditions with corresponding actions for each condition. Cases are evaluated in order; after a case returns true, later cases are not evaluated at all.

For this preview, switch supports the following parameters:

• case
  • condition - the condition that is being tested
  • execute - one or more actions to perform when the specified condition is met (see the execute command for the list of supported actions)

throw

Throws an error when it is reached during an assembly flow, usually as a result of a condition being met. For this preview, throw supports the following parameters:

• error - one of the following counted errors that are supported by the catch command:
  • BadRequestError: An error occurred while trying to access the request. This is not supported by the default catch; to catch this condition, specify it in your catch definition.
  • ConnectionError: An error occurred while establishing a connection to another URL.
  • LimitExceededError: The request exceeds the rate limit threshold that is specified in the API.

validate

Validates payload or parameters based on schemas that are located in the API.

Note: For this preview, if you create your own API and use the validate policy, the API must include the following configuration setting (which is also included in the sample demo.yaml API):

x-ibm-configuration:
  compatibility:
    suppress-limitation-errors: true

For this preview, validate supports the following parameters:

• mode
  • openapi-request- Validate request body and parameters. Effectively the next 2 options at the same time.
  • openapi-request-body - Validate request body as defined by the operation object in the OpenAPI document
  • openapi-request-parameters - Validate request parameters (cookie, header, query parameters, and path) as defined in the path or operation object in the OpenAPI document.
  • openapi-response-body - Validate the message body as specified by the responses section of the API operation (none, default, or based on response status code)
  • ref - Use a schema defined in the API's components/schemas section
• input: Indicate which context to validate (request, message, response, and so on)
• error_response: Indicate whether a validation failure should result in 400 BAD REQUEST or 500 INTERNAL ERROR

catch command

The catch command specifies a list of supported error conditions and the actions to be performed when one of those conditions is encountered by the execute command.

The catch command is a list of objects, each of which has two fields: errors and execute. The errors field can be any combination of the supported errors to catch (3 currently). The execute field contains a list of actions to perform when a specified error is encountered.

errors

Catches errors that occur during an API call. For this preview, catch supports the following errors:

• BadRequestError: An error occurred while trying to access the request. This is not supported by the default catch; to catch this condition, specify it in your catch definition.
• ConnectionError: An error occurred while establishing a connection to another URL.
• LimitExceededError: The request exceeds the rate limit threshold that is specified in the API.

execute

A list of actions to perform when one of the actions in the execute throws an error that is listed in the errors field. The actions that are supported by the execute parameter are the same actions that are supported by the execute command.

finally command

The finally command specifies the final API actions to perform after all of the actions in the main execute command and the catch command are completed. The actions that are supported by finally are the same actions that are supported by the execute command.