Request handling
6 minute read
HTTP Requests
API Builder will pre-process HTTP requests. Any errors processing, decoding, or validating the request will result in an automatic response. Flows will only ever be executed with valid inputs. If the HTTP request matches a bound OpenAPI operation, then all of the defined OpenAPI operation inputs are gathered into flow inputs and handled as described in the following sections.
Flow inputs
When the HTTP request is processed, and its parameters, and body are decoded as per the OpenAPI operation, then their values are delivered to the flow. The following sections detail how the flow inputs are achieved.
Request parameters
OpenAPI parameters are processed as described in the following sections. Parameter encoding styles are supported.
If any parameter fails to parse, or if the parameters fail to validate against their JSON schema, it will result in a 400 Bad Request error response being sent to the client. The flow will not be executed.
Request cookie parameters
If the OpenAPI operation defines cookie parameter(s), they will be decoded with respect to the defined OpenAPI parameter and can be accessed from within the flow using their case-sensitive parameter names from $.request.cookies. For example, $.request.cookies.session.
Request header parameters
If the OpenAPI operation defines header parameter(s), they will be decoded with respect to the defined OpenAPI parameter and can be accessed from within the flow using their case-sensitive parameter names from $.request.headers. For example, $.request.headers.limit.
All remaining non-parameter HTTP request headers are lower-cased and will be passed into the flow, and are accessible from $.request.headers. For example, $.request.headers['content-type'].
Request query parameters
If the OpenAPI operation defines query parameter(s), they will be decoded according to the OpenAPI specification and can be accessed from within the flow using their case-sensitive parameter names from $.request.query. For example, $.request.query.limit.
Request path parameters
If the OpenAPI operation defines path parameter(s), they will be decoded according to the OpenAPI specification and can be accessed from within the flow using their case-sensitive parameter names from $.request.path. For example, $.request.query.path.
Request body
If the client sends a HTTP request body, it will be parsed and validated according to the OpenAPI request body object. If the OpenAPI specification does not define a body, and the client does not send one, then the body will be undefined. Otherwise, the body is parsed and validated and delivered to the flow as $.request.body.
The OpenAPI supports decoding and validating the body for the following content-types:
application/x-www-form-urlencodedmultipart/form-dataapplication/jsonapplication/*+jsonapplication/xml¹application/*+xml¹application/xml-dtd¹application/xml-external-parsed-entity¹image/svg+xml¹model/x3d+xml¹
- XML types will be handled as strings and are not decoded. However, the XML can be processed within the flow with the XSLT flow-node.
All other unknown content-type will be handled as Buffer.
The following sections provide examples of how to achieve common HTTP patterns with OpenAPI request body object.
JSON body
If the OpenAPI operation defines content with application/json, then it will be automatically decoded and verified against the supplied JSON schema, and will be accessible from $.request.body.
For example, this defines the body is JSON, and the decoded User object is the value of $.request.body:
content:
'application/json':
schema:
$ref: '#/components/schemas/User'
Any failure to validate the request body will result in a 400 Bad Request error and the flow will not be executed.
Multipart and form body
If the OpenAPI operation defines content with x-www-form-urlencoded or multipart/form-data, then the client request body will be automatically decoded and verified against the supplied JSON schema, and non-file fields (see multipart files) will be accessible from $.request.body.
For example, this form field id can be accessed from $.request.body.id:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
id:
type: string
format: uuid
Any failure to validate the request body will result in a 400 Bad Request error and the flow will not be executed.
Multipart files
Multipart files are handled differently than regular form fields. As part of the HTTP request pre-processing, files are uploaded to the OS temp directory (e.g. /tmp), and can be accessed later from the flow when needed, rather than keeping the value in memory. The field values are the actual file location on disk.
For example, this form field image can be accessed from $.request.body.image:
requestBody:
content:
multipart/form-data:
schema:
properties:
image:
type: string
format: binary
The $.request.body.image is an object that fully describes the uploaded file:
image: {
file: '/tmp/abc-123-unique-id/image.png',
filename: 'image.png',
encoding: '7bit',
mimetype: 'image/png'
}
Note
API Builder does not support arrays of files. They have to be defined as different keys.Raw text body
If the OpenAPI operation defines content with text/plain, then it will be verified against any supplied JSON schema, and will be accessible from $.request.body.
requestBody:
content:
text/plain:
schema:
type: string
maxLength: 1024
Raw body
If the OpenAPI operation defines only an application/octet-stream, or defines media-types that is not processable (i.e. that are not application/*json, x-www-form-urlencoded, multipart/form-data, or text/plain), then the body will be accessible from $.request.body as a Buffer, and will not be validated against the JSON schema.
Request ID
Beginning in @axway/api-builder-plugin-ft-oas@1.6.0, the API Builder HTTP request ID is accessible from $.request.id. This can be useful for traceability.
Request body validation
Before invoking the flow, API Builder will validate the request body with respect to the OpenAPI operation. For performance, JSON schema validation occurs “just in time”. This means that the first time the request is validated for this particular operation, the JSON schema will be compiled and cached for future use. Then, the request body will be validated against the compiled JSON schema. This can lead to production errors if the JSON schema is invalid (e.g invalid references) and if there is inadequate testing.
Note
It is a good idea to develop a robust set of tests for your application before going to production. You can use the supplied mocha tests, or use postman for regression testing.Failure to validate the request’s body against the OpenAPI operation will result in a 400 Bad Request error response being sent to the client. The flow will not be executed.
Disabling request validation
There is possibility to disable the request validation via Request validation option.
Automatic responses
If API Builder encounters errors with the client’s HTTP request, it will send automatic errors without invoking the flow. The errors are detailed in the following sections. Note that your OpenAPI document should include these errors in its specification for correctness. A list of errors has been provided for convenience.
- Any request for a bound OpenAPI operation that fails to parse, or fails to validate with respect to the OpenAPI specification, will result in an automatic
400 Bad Requesterror response being sent to the client. The flow will not be executed. - Any request failing authentication will result in an an automatic
401 Unauthorizederror response being sent to the client. The flow will not be executed. - Any request for an unimplemented method will result in an automatic
404 Not Founderror response being sent to the client.
Bad request errors (400)
The client sent an invalid request. The client needs to examine the error(s) and their request to determine how to correct the issue.
{
"success": false,
"code": 400,
"request-id": "a-unique-identifier",
"message": "A summary message",
"errors": [
"Detailed error"
]
}
Unauthorized (401)
The client failed to send valid credentials, or the credentials were invalid.
{
"id":"com.appcelerator.api.unauthorized",
"success": false,
"message": "Unauthorized"
}
Not found (404)
The client tried to access a resource that does not exist. This may be because the OpenAPI operation is not yet bound, or it may be that the client provided an incorrect HTTP method or path.
{
"success": false,
"code": 404,
"request-id": "a-unique-identifier",
"message": "Not found"
}