Interfaces

Interfaces are used to shared fields across models and union types. Models and union types can extend 0 or more interfaces, but interfaces themselves are abstract and cannot be instantiated.

To define an interface, declare an interface:

        "person": {
            "fields": [
                { "name": "email", "type": "string", "required": false },
                { "name": "name", "type": "string", "required": false }
            ]
        }
        

A scala code generator may produce the following to represent this interface:

        sealed trait Person {
            def email: Option[String]
            def name: Option[String]
        }
        

To indicate a particular model extends this interface:

        "models": {
            "guest": {
                "interfaces": ["person"],
                "fields": [
                    { "name": "session_id", "type": "string" },
                    { "name": "email", "type": "string", "required": false },
                    { "name": "name", "type": "string", "required": false }
                ]
            }
        }
        

API Builder will enforce that any model that extends an interface will declare fields that match the interface (by name, type, and required).

A scala code generator may produce the following to represent this interface:

        case class Guest(
            sessionId: String,
            override val email: Option[String] = None,
            override val name: Option[String] = None
        ) extends Person
        

Union types behave similarly to models with a few additional features:

• You can declare an interface with the same name as a union type, as long as the union type documents that you are intentionally doing so by listing the interface.
• Any type listed in the union type will automatically inherit the interface defined on the union type

As an example, we can define the following union type:

            "unions": {
                "person": {
                    "discriminator": "discriminator",
                    "interfaces": ["person"],
                    "types": [
                        { "type": "guest" }
                    ]
                }
            },
        

This means that the guest model is of type person and will automatically inherit the person interface (no need to explicitly specify the interface on the guest model).

For a complete example of an api.json file demonstrating interfaces, see example-interface.json