API Request

Use to start an API workflow

The API Request Node is used to create HTTP APIs in Sanbox. Every API Workflow starts with an API Request Node and ends with an API Response Node.

Not Just APIs. The API Request and Response Node can also be used to serve web pages. You can make a server-side rendering web app in Sanbox using Text Templates.

How Sanbox APIs Accept Data

Sanbox's primary/working data format is JSON. Any well structured object in Sanbox is JSON. However, APIs you create in Sanbox support numerous media types. Sanbox converts anything it receives into JSON inside your workflow. Sanbox APIs support the following media types:

  • application/json

  • application/xml (As json string containing XML)

  • text/*

  • application/octet-stream

  • image/*

  • application/x-www-form-urlencoded

  • multipart/form-data

By default, if a media type is received that Sanbox does not implicitly handle, an error is thrown to the consumer. If you want to allow all media types, you can change the runtime.json config setting HttpWebServer.Security.AllowAllMediaTypes on your Runtime to true. When this setting is true, Sanbox will handle content from these media types as raw bytes.

Sanbox internally handles raw bytes in their raw format. Whenever you view an object containing a byte array in Sanbox Designer, the bytes are displayed in Base64 Encoding.

Configuration

Configuring the API Request Node

Summary

The summary is just for your organizational purposes. Its a quick description of what the API does.

Feature Peek: A feature is in the works to generate specification information in formats like OpenAPI for your APIs in Sanbox. Its planned that the Summary will be used in the spec.

Path Template

The path template is the endpoint of your new API. This endpoint can be a template. Templates for paths in Sanbox follow the URI Template Spec RFC6570 standard and are different than the Text Template system in Sanbox. The following are examples of templates:

Template

Matches

customer/{id}

customer/12

{department}/employee/{id}

marketing/employee/9

files{/folders*}

files/programs/lumisan/sanbox

{environment}/{version}/customers

prod/v1/customers

{/environment}/{/version}/customers

prod/v1/customers and v1/customers

URL endpoints in Sanbox are case-sensitive

The API Request Node outputs dynamic template data in the parameters property. For example, a template of customer/{id} being tested on a Runtime on a developer machine with the URL https://localhost/customer/12?getOrderData=true causes a Web API Request node to output the following:

{
"path": "/customer/12",
"headers": {
"cache-Control": [
"no-cache"
],
"connection": [
"keep-alive"
],
"content-Type": [
"application/xml"
],
"accept": [
"application/xml"
],
"accept-Encoding": [
"gzip, deflate"
],
"host": [
"localhost"
],
"user-Agent": [
"PostmanRuntime/7.13.0"
],
"postman-Token": [
"e5d2c2ef-0ae2-4a6f-9396-18e995af9c52"
]
},
"cookies": {},
"parameters": {
"id": "12"
},
"queryParameters": {
"getOrderData": "true"
},
"httpMethod": "GET",
"body": null
}

Query parameters do not get matched against the endpoint template. If multiple query parameters are used with the same key, the last value is used for that key.

Operations

Every API Request Node can handle one or more HTTP Methods or Operations for an endpoint. In Sanbox, you can have multiple Workflows share the same endpoint, as long as they handle different operations.

When configuring operations (edit button next to operation) that support a body, you can configure a model to be used to validate the body against.

Configuring an Operation

When validation fails, an error is thrown by the API Request Node with JSONPath information to which property/properties failed validation.

To generate a user friendly validation message for a web application, leave operation models dynamic and use the Validate Model Node.

CSRF Token

For APIs that use cookies or basic authentication, you can check the Validate CSRF Token checkbox to verify a CSRF Token. Read the guide on Using CSRF Token in APIs to learn more or check out this Wikipedia Page to learn more about CSRF attacks.