https://typeapi.org/

TypeAPI

  * Home
  * Specification
  * Generator

[github-32]

TypeAPI

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

Specification Generator

Our goal is to remove the need to develop custom client SDKs for an
REST API.
Once you have described your API with a TypeAPI specification you
automatically get a ready to use client SDK.

---------------------------------------------------------------------

Simple API

A simple GET endpoint which returns a hello world message.

TypeAPI

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

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": {
    "com.acme.api.todo.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": {
    "com.acme.api.todo.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": {
    "com.acme.api.hello.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

interface HelloWorld {
    message?: string
}

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

---------------------------------------------------------------------

Tags

Through a tag you can group operations

TypeAPI

{
  "operations": {
    "com.acme.api.todo.create": {
      "description": "Inserts a new todo entry",
      "method": "POST",
      "path": "/todo",
      "arguments": {
        "payload": {
          "in": "body",
          "schema": {
            "$ref": "Todo"
          }
        }
      },
      "return": {
        "schema": {
          "$ref": "Message"
        }
      },
      "tags": ["todo"]
    },
    "com.acme.api.product.create": {
      "description": "Inserts a new product",
      "method": "POST",
      "path": "/product",
      "arguments": {
        "payload": {
          "in": "body",
          "schema": {
            "$ref": "Product"
          }
        }
      },
      "return": {
        "schema": {
          "$ref": "Message"
        }
      },
      "tags": ["product"]
    }
  },
  "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