Specification

Table of Contents

• Introduction
• Root
  • Operations
    • Return
    • Arguments
    • Throws
  • Definitions
• Appendix

Introduction

The TypeAPI specification defines a JSON format to describe REST APIs for type-safe code generation.

Goals

• Provide a format to generate clean and ready to use code
• Provide a simple and stable specification where you can easily build a code generator
• Optimized for static typed and object-oriented programming languages

Non-Goals

• Describe every possible REST API structure and JSON payload
• Supporting many different Content-Types like XML or x-www-form-urlencoded
• Providing complex JSON validation capabilities

Reasoning

For a long time the OpenAPI community was divided into two communities, one building documentation tools and the other trying to build code generation tools. Building documentation tools has very different requirements than building code generation tools. For a documentation tool you can simply render and show all defined endpoints and constraints, a code generation tool on the other side needs to understand the structure and relations of your model.

The OpenAPI specification has moved more and more to the documentation community by directly integrating JSON Schema into the specification. The problem with JSON Schema and code generation is, that JSON Schema is a constraint system, based on such constraints it is very difficult or impossible to build a clean code generator since the constraints only define what is not allowed. For a code generator you like to have a schema which explicit models your data structure.

With TypeAPI we want build a new home for the code generation community. Conceptual the main difference is that with OpenAPI you describe routes and all aspects of a route, at TypeAPI we describe operations, an operation has arguments and those arguments are mapped to values from the HTTP request. Every operation returns a response and can throw exceptions which are also mapped to a HTTP response. An operation basically represents a method or function in a programming language. This approach makes it really easy to generate complete type safe code.

Root

Every TypeAPI has a Root definition. The Root must contain at least the operations and definitions keyword i.e.:

{
    "operations": {
        "com.acme.api.hello.getMessage": { ... },
    },
    "definitions": {
        "TypeA": { ... },
        "TypeB": { ... }
    }
}

Operations

The operations keyword contains a map containing Operation objects. The key represents the global identifier of this operation. In general we recommend to use as prefix for every operation key the reverse name of your domain (i.e. com.acme.api.myOperation) which makes it globally unique. The generated client code always uses the last part of your operation key as method name.

{
    "operations": {
        "com.acme.api.hello.getMessage": {
            "description": "Returns a hello world message",
            "method": "GET",
            "path": "/hello/world",
            "return": {
                "schema": {
                    "$ref": "Hello_World"
                }
            }
        }
    },
    "definitions": {
        "Hello_World": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                }
            }
        }
    }
}

Return

Every operation can define a return type. In the above example the operation simply returns a Hello_World object.

Arguments

Through arguments you can map values from the HTTP request to specific arguments. In the following example we have an argument status which maps to a query parameter and an argument payload which contains the request payload.

{
    "operations": {
        "com.acme.api.hello.insertMessage": {
            "description": "Inserts and returns a hello world message",
            "method": "POST",
            "path": "/hello/world",
            "arguments": {
                "status": {
                    "in": "query",
                    "schema": {
                        "type": "integer"
                    }
                },
                "payload": {
                    "in": "body",
                    "schema": {
                        "$ref": "Hello_World"
                    }
                }
            },
            "return": {
                "schema": {
                    "$ref": "Hello_World"
                }
            }
        }
    },
    "definitions": {
        "Hello_World": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                }
            }
        }
    }
}

This would map to the following HTTP request.

POST https://api.acme.com/hello/world?status=2
Content-Type: application/json

{
  "message": "Hello"
}

Throws

Besides the return type an operation can return multiple exceptional states in case an error occurred. Every exceptional state is then mapped to a specific status code i.e. 404 or 500. The generated client SDK will then throw a fitting exception containing the JSON payload in case the server returns such an error response code. The client will either return the success response or throw an exception. This greatly simplifies error handling at your client code.

{
    "operations": {
        "com.acme.api.hello.getMessage": {
            "description": "Returns a hello world message",
            "method": "POST",
            "path": "/hello/world",
            "return": {
                "schema": {
                    "$ref": "Hello_World"
                }
            },
            "throws": [{
                "code": 404,
                "schema": {
                    "$ref": "Error"
                }
            }, {
                "code": 500,
                "schema": {
                    "$ref": "Error"
                }
            }]
        }
    },
    "definitions": {
        "Hello_World": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                }
            }
        },
        "Error": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                }
            }
        }
    }
}

Definitions

The definitions keyword maps to the TypeSchema specification and represents a map containing Struct, Map and Reference types. Those types are then used to describe incoming and outgoing JSON payloads.

Appendix

The single source of truth of TypeAPI is the TypeSchema meta schema which describes the TypeAPI specification. You can find the current TypeSchema at our repository. The following section contains a HTML representation which we automatically generate from this schema.

{
  "in": String,
  "schema": typeschema:BooleanType | typeschema:NumberType | typeschema:IntegerType | typeschema:StringType | typeschema:ReferenceType,
}

Map (Argument)

{
  "method": String,
  "path": String,
  "return": Return,
  "arguments": Arguments,
  "throws": Array (Throw),
  "description": String,
  "stability": Integer,
  "security": Array (String),
  "authorization": Boolean,
  "tags": Array (String),
}

Map (Operation)

{
  "code": Integer,
  "schema": typeschema:ReferenceType,
}

{
  "type": String,
}

{
  "name": String,
  "in": String,
}

{
}

{
}

{
  "tokenUrl": String,
  "authorizationUrl": String,
  "scopes": Array (String),
}

{
  "code": Integer,
  "schema": typeschema:ReferenceType,
}

{
  "$import": typeschema:Import,
  "baseUrl": String,
  "security": SecurityHttpBasic | SecurityHttpBearer | SecurityApiKey | SecurityOAuth2,
  "operations": Operations,
  "definitions": typeschema:Definitions,
}