Skip to main content
Version: AMF v5.x.x

Payload validation with AMF

You can use AMF to validate incoming payloads to an API already deployed and running. To do so, you need to:

  1. Get the AMF Shape to use for validation
  2. Create an AMFShapePayloadValidator for that shape
    1. with the AMFElementClients payloadValidatorFor() method
  3. Validate payloads

Get the AMF Shape to use for validation​

When AMF parses an API it returns a Document that encodes a WebApi, which is the AMF API Contract Model based on the original API:

api to webapi model

You can obtain the specific Shape you want from this object.

The AMF API Contract Model documentation has more information about the WebApi object.

Create a AMFShapePayloadValidator for a specific Shape​

You can create an AMFElementClient from any AMFConfiguration simply by doing configuration.elementClient().

All AMFElementClients have the methods payloadValidatorFor(shape, mediatype, mode) or payloadValidatorFor(shape, fragment) that return an AMFShapePayloadValidator:

AMFShapePayloadValidator interface
trait AMFShapePayloadValidator {
  def validate(payload: String): Future[AMFValidationReport]
  def validate(payloadFragment: PayloadFragment): Future[AMFValidationReport]
  def syncValidate(payload: String): AMFValidationReport
}

Validate the payloads​

To validate payloads use the AMFShapePayloadValidator methods:

  • validate(payload: String): Future[AMFValidationReport]
    • validates a given payload
    • Returns a completable future of the AMFValidationReport object containing detailed information about any errors
  • validate(payloadFragment: PayloadFragment): Future[AMFValidationReport]
  • syncValidate(payload: String): AMFValidationReport
    • Validates a payload synchronously
    • Returns the AMFValidationReport directly

Example code for payload validation​

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 following the previous steps:

  1. Get the AMF Shape to use for validation
    1. The User schema we want can be obtained from the Requests Payload object
  2. Create an AMFShapePayloadValidator for that shape
    1. with the AMFElementClients payloadValidatorFor() method
  3. Validate payloads
    1. with the AMFShapePayloadValidators validate() methods

Code extracted from the examples GitHub repository.

Custom payload validation plugin​

AMF lets you create a payload validation plugin by extending the AMFShapePayloadValidationPlugin in Scala or Java, or implementing the JsAMFPayloadValidationPlugin in Javascript or Typescript.

For example: given the following implementations of payload validation plugins:


You can now use these to validate payloads:


Code extracted from the examples GitHub repository.