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

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]
  • Validates a payload from an AMF PayloadFragment
• 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:

Java

Code extracted from the examples GitHub repository.

JavaScript

Code extracted from the examples GitHub repository.