Skip to main content

Payload validation with AMF

You can use AMF to validate incoming payloads to an API already deployed and running. For example, consider a RAML API that declares:

  • A User schema with firstname, lastname, and age properties
  • A /users endpoint with an HTTP POST method that requires a User object as body parameter
#%RAML 1.0
title: API with Types
types:
User:
type: object
properties:
firstname: string
lastname: string
age: number
/users:
post:
body:
application/json:
type: User

To confirm that a given payload is a valid User, you can use AMF payload validation. To do so:

  1. Get the AMF payload shape
  2. Create a PayloadValidator
  3. Validate payloads

Get the AMF payload shape#

When AMF parses an API, it:

  • Returns a Document that encodes a WebApi, which is the AMF WebApi graph model of the original API
  • Abstracts the HTTP methods to Operation objects

api to webapi model

The AMF Model Documentation has more information on each intermediate model. The payload shape we'll use can be obtained from an Operation Request or Response object.

Create a PayloadValidator#

The payload shape (or schema) is a specific implementation of the AnyShape class, which implements the ValidatorAware interface:

amf.client.model.domain.ValidatorAware.scala
trait ValidatorAware {
def payloadValidator(mediaType: String): ClientOption[PayloadValidator]
def payloadValidator(mediaType: String, exec: BaseExecutionEnvironment): ClientOption[PayloadValidator]
def payloadValidator(mediaType: String, env: Environment): ClientOption[PayloadValidator]
def parameterValidator(mediaType: String): ClientOption[PayloadValidator]
def parameterValidator(mediaType: String, exec: BaseExecutionEnvironment): ClientOption[PayloadValidator]
def parameterValidator(mediaType: String, env: Environment): ClientOption[PayloadValidator]
}

This interface defines methods to create a PayloadValidator from an AnyShape class, given the mediaType and optional BaseExecutionEnvironment or Environment objects.

There are two distinct payload validators:

  • payloadValidator
    • Validates types, values, and constraints in strict mode
  • parameterValidator
    • Validates query parameters, where different types may be sent as strings; fails only if there is no applicable schema

Validate the payloads#

To validate a payload with PayloadValidator, use the following methods:

  • isValid(mediaType: String, payload: String): ClientFuture[Boolean]
    • Validates a payload given its media type in fail-fast mode
    • Stops execution when it encounters any violation
    • Used for checking payload validity
  • validate(mediaType: String, payload: String): ClientFuture[ValidationReport]
    • Returns a ValidationReport object containing detailed information about any errors
  • validate(payloadFragment: PayloadFragment): ClientFuture[ValidationReport]
  • syncValidate(mediaType: String, payload: String): ValidationReport
    • Validates a payload synchronously
    • Returns the ValidationReport

Example code for a payload validator#

The following code example validates the previously mentioned User schema with the payload validation methods:

Code extracted from the examples GitHub repository.

Last updated on by arielmirra