Data examples are very important in a data exchange design process

In particular, they make it possible to: 

  • Validate the modeling with concrete examples
  • Generate functionally coherent API simulations (Mocks) to accelerate development and obtain rapid feedback

Akwatype allows to describe examples on types and facades but most of the time the examples are constituted on types. Indeed, since Akwatype will be able to use them directly on facades by transforming them automatically (we will come back to this aspect a little later), it is almost never necessary to describe examples on facades.

In this article we will use the following types:

type Person{
    name:String
    firstName:String
    age:Integer
    address:Address
}

type Address {
   street:String
   city:String
   zipCode:String
   country:String 
}

 

Declaration of an example

Example are declared in facades files

  • A good practice is to declare the examples in separate files prefixed with an x to identify them easily.
    Similarly, it is a good practice to prefix the name of examples with x to easily identify them (eg. xPerson)

To describe an example, akwatype allows you to first select the type (or facade) on which the example applies (with the keyword on) and to indicate the fields you want to keep with their value. All fields that are not named in the example are ignored.

  • For scalar values (String, Integer, Boolean....) the value is directly filled in the example
  • For complex type values (an address for example) the value is replaced by the name of an example of this type.
    This mechanism allows to compose complex examples with a strong reuse of already defined examples.
 
example xLeo on Person{
    name: "Caron"
    firstName:"Leo"
    age: 28
    address:xParis
}

example xParis on Address{
    street:"Avenue Carnot"
    zipCode: "75000"
    city: "Paris"
    country: "France"
}

Generated example for xLeo (on Person)

{
  "name": "Caron",
  "firstName": "Leo",
  "age": 28,
  "address": {
    "street": "Avenue Carnot",
    "city": "Paris",
    "zipCode": "75000",
    "country": "France"
  }
}

 

Using an example as a template for a new example

Akwatype allows you to use an existing example as a template to create a new one.

To do this, use the template declaration in the properties block of the new example.

The template declaration can be followed by except which allows you to define a list of fields that you do not want to use in the new example

 

This xParis2 example templated on xParis

example xParis on Address{
    street:"Avenue Carnot"
    zipCode: "75000"
    city: "Paris"
    country: "France"
}

example xParis2 on Address{
    properties {
        template: xParis except(country)
    }
    street:"rue Didrot"
}

will generate this Json example

{
  "street": "rue Didrot",
  "city": "Paris",
  "zipCode": "75000"
}

 

Examples on facades and automatic transformations 

A great strength of Akwatype is its ability to automatically transform a Json message corresponding to a type or a facade into a new Json corresponding to another facade based on the same type.

This capability allows to reuse the examples defined on a type for all facades based on this type

Let's assume that we have defined the following facade PersonDTO

facade PersonDTO on Person{
    familyName:name
    city:address.city
    age
}

If we use the generated example for xLeo as input on PersonDTO

{
  "name": "Caron",
  "firstName": "Leo",
  "age": 28,
  "address": {
    "street": "Avenue Carnot",
    "city": "Paris",
    "zipCode": "75000",
    "country": "France"
  }
}

 

We will automatically get this Json 

{
  "familyName": "Caron",
  "city": "Paris",
  "age": 28
}

 

This type of transformation can be directly tested in akwatype in the projection area of the type and facade description editor

 

Usage of data examples on API description

It is of course in the use of the examples in the description of the routes of the services that this posibility takes all its direction.

You define your examples on the business model (types) and Akwatype automatically adjusts them to all facades you use to describe your APIs.

The consistency of the examples is therefore automatically ensured and the time saved in describing and maintaining the examples is considerable.

 

Example of usage of data examples in route response

responses {
    "200": PersonDTO {
        description:"Minimum information about a person"
        examples{
            Leo:xLeo
            Leslie:xLesli
        }
    }
}

Rendering in swagger editor

 

The examples can of course also be used to describe the payload and headers of messages

message trainer{
    headers: StandardMessageHeaders
    payload: TrainerDTO
    examples {
       example1 {
           headers: xStandardMessageHeaders
           payload: xLeoTrainer
       }
    }
}