TypeAPI

An OpenAPI alternative to describe REST APIs for type-safe code generation.

Specification Editor Generator

Simple API

A simple GET endpoint which returns a hello world message.

TypeAPI

{
  "operations": {
    "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"
        }
      }
    }
  }
}

Client SDK

const client = new Client()
client.getMessage(): HelloWorld

interface HelloWorld {
    message?: string
}

Argument Query

Through the arguments keyword you can map values from the HTTP request to an argument, in this example we map the HTTP query parameters to the startIndex and count argument

TypeAPI

{
  "operations": {
    "getAll": {
      "description": "Returns available todo entries",
      "method": "GET",
      "path": "/todo",
      "arguments": {
        "startIndex": {
          "in": "query",
          "schema": {
            "type": "integer"
          }
        },
        "count": {
          "in": "query",
          "schema": {
            "type": "integer"
          }
        }
      },
      "return": {
        "schema": {
          "$ref": "Todos"
        }
      }
    }
  },
  "definitions": {
    "Todos": {
      "type": "object",
      "properties": {
        "entries": {
          "type": "array",
          "items": {
            "$ref": "Todo"
          }
        }
      }
    },
    "Todo": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        }
      }
    }
  }
}

Client SDK

const client = new Client()
client.getAll(startIndex: number, count: number): Todos


interface Todos {
    entries?: Array<Todo>
}

interface Todo {
    title?: string
}

Argument Body

In this example we map the HTTP request body to the payload argument

TypeAPI

{
  "operations": {
    "create": {
      "description": "Inserts a new todo entry",
      "method": "POST",
      "path": "/todo",
      "arguments": {
        "payload": {
          "in": "body",
          "schema": {
            "$ref": "Todo"
          }
        }
      },
      "return": {
        "schema": {
          "$ref": "Message"
        }
      }
    }
  },
  "definitions": {
    "Todo": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        }
      }
    },
    "Message": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Client SDK

const client = new Client()
client.create(payload: Todo): Message

interface Todo {
    title?: string
}

interface Message {
    success?: boolean
    message?: string
}

Throws

Through the throws keyword you can define specific error payloads, the generated client will then also throw an exception in case the server returns such an error code

TypeAPI

{
  "operations": {
    "getMessage": {
      "description": "Returns a hello world message",
      "method": "GET",
      "path": "/hello/world",
      "return": {
        "schema": {
          "$ref": "Hello_World"
        }
      },
      "throws": [{
        "code": 500,
        "schema": {
          "$ref": "Error"
        }
      }]
    }
  },
  "definitions": {
    "Hello_World": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    },
    "Error": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Client SDK

const client = new Client()
client.getMessage(): HelloWorld throws Error

interface HelloWorld {
    message?: string
}

interface Error {
    success?: boolean
    message?: string
}

Tags

Through the dot notation at the operation key you can group your operations into logical units

TypeAPI

{
  "operations": {
    "todo.create": {
      "description": "Inserts a new todo entry",
      "method": "POST",
      "path": "/todo",
      "arguments": {
        "payload": {
          "in": "body",
          "schema": {
            "$ref": "Todo"
          }
        }
      },
      "return": {
        "schema": {
          "$ref": "Message"
        }
      }
    },
    "product.create": {
      "description": "Inserts a new product",
      "method": "POST",
      "path": "/product",
      "arguments": {
        "payload": {
          "in": "body",
          "schema": {
            "$ref": "Product"
          }
        }
      },
      "return": {
        "schema": {
          "$ref": "Message"
        }
      }
    }
  },
  "definitions": {
    "Todo": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        }
      }
    },
    "Product": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        }
      }
    },
    "Message": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Client SDK

const client = new Client()
client.todo().create(payload: Todo): Message
client.product().create(payload: Product): Message

interface Todo {
    title?: string
}

interface Product {
    title?: string
}

interface Message {
    success?: boolean
    message?: string
}

Edit this page