TypeAPI an alternative to OpenAPI

This post introduces TypeAPI a new specification to describe REST APIs which is optimized for code generation. You probably think, we have already settled for OpenAPI why do we need a new specification. With this post I would like to answer this question and describe the ideas and future plans for TypeAPI.

What is the difference to OpenAPI?

The main goal of OpenAPI is to be able to document almost any aspect of an REST API, i.e. you can specify different response payloads JSON or XML, example payloads, webhooks and through JsonSchema you can describe almost any JSON structure. While this flexibility is really great for documentation it is more challenging for code generation. TypeAPI on the other hand is build from the ground up optimized for code generation.

With OpenAPI you have the great value, that you get many apps to render a documentation for your API, with TypeAPI you have the great value, that you don`t need to build a client SDK for your API, since TypeAPI can automatically generate high quality client SDKs. This can be especially useful for teams who are not familiar with different programming languages, they only need to generate a TypeAPI spec and then get a ready to use client SDK for most popular programming languages. Currently only large companies can have a dedicated team to manage different client SDKs, with TypeAPI we want to help every company to be able to provide a great client SDK.

OpenAPI has already a client generator

You may think, this sounds great but OpenAPI has already the ability to generate a client SDK based on an OpenAPI spec. While this is true, the problem is in the details and from our view there is currently no code generator available which can generate high quality and ready to use code. I have also wrote a posts explaining why OpenAPI and JsonSchema are not great for code generation and we think this is a problem which is not fixable at the specification level (insert favorite XKCD here). Because of this we have created TypeAPI to provide a competitor to OpenAPI and then the community can decide whether TypeAPI provides a value. Since TypeAPI is stricter than OpenAPI we can easily generate an OpenAPI spec based on a TypeAPI spec, vice versa this is not easy possible.

Conceptual difference to OpenAPI

Ok great, but can you explain the difference to OpenAPI and how TypeAPI is optimized for code generation. Sure so the first conceptual difference is: At TypeAPI we describe operations instead of paths. Let me show you an example:

Here you can see the basic building block of TypeAPI is an operation. At the OpenAPI spec you would start with describing a path. The operation then contains arguments which are mapped to a value from the HTTP request. The operation then returns a response or throws an exception which are also mapped to a client or server error response code. You probably already see that we basically model with an operation all concepts of a function. Another main difference is that TypeAPI uses TypeSchema instead of JsonSchema, this gives us the ability to generate high quality data models based on the described types.

We have many years of experiences building code generation tools for the OpenAPI and JsonSchema echosystem. We came to the conclusion that this operation/RPC oriented way of describing an REST API provides the best way to generate high quality client SDKs. In the end an SDK user does not care about HTTP paths or request methods, the user only wants to have self describing method names to consume the remote API. With TypeAPI our main goal is to be able to generate high quality and ready to use code. Our goal is not to be able to describe every exotic API.

The Future we envision

Currently API Integration is a large topic and many developers spend hours of development time to integrate various REST APIs. With TypeAPI we want to improve this process. We think there is a huge value in code generation especially in current times where we have a developer shortage and development time is really expensive.

The TypeScript community has created the Definitely Typed repository to describe the types of many popular Javascript app, in a similar idea we have created TypeHub, a place where anybody can create a TypeAPI description for a REST API and where you can download the fitting client SDK. This should help our community to quickly create definitions also for REST APIs where no client SDK is provided.

Another great future topic is, that TypeAPI can be easily extended to describe different kinds of web services. We have started with REST APIs but we could also add different kinds of mappings i.e. for GraphQL or JsonRPC, we only need to add a fitting mapping configuration. This is a future plan but we think that there is a great potential.

Closing words

This was a first introduction to the TypeAPI specification. Currently the specification is in beta phase. I hope you are as excited as we are about the future of TypeAPI and please checkout our website or GitHub repository.

You may have noticed that we have talked several times about high quality code, we know that such a claim is easy to made but please take our word for granted and let us know in case you have any problems regarding the generated code.

The best way to support our initiative is to create a TypeAPI spec for your REST API and try to use our generated client SDK, since in the end the value of every specification depends on the users. Another great support is to register your spec at our TypeHub portal. If you want to give us feedback please open an issue at our repository or you can also contact us directly through our website.

Best regards, Christoph.