Skip to main content

Create an API Specification

Use @api-ts/io-ts-http to define a standalone API specification in TypeScript.

What problem does io-ts-http solve?​

Web services use an API as a contract to describe how clients should communicate with servers.

When a server receives a request from a client, the server needs to answer a few questions before it can begin fulfilling that request:

  • Did the client satisfy the API contract?

    For example, did the client provide a number where I asked for a number?

  • If the client satisfied the API contract, did it give me values I can use?

    For example, if the client is requesting to reserve some number of concert tickets, did the client try to reserve at least 1 ticket? How can I fulfill a request to reserve -2 tickets?

We'll call the first type analysis and the second semantic analysis.

io-ts-http lets you define API contracts to an arbitrary degree of precision, removing the burden of semantic analysis from your business logic.

Create your first apiSpec​

First, create a new directory for a Node.js project by running the following commands in your terminal:


$ mkdir api-ts-example
$ cd api-ts-example

In your new directory, create a package.json file:

package.json

{
"name": "api-ts-example",
"scripts": {
"build": "tsc --lib es2015 --esModuleInterop *.ts"
},
"dependencies": {
"@api-ts/io-ts-http": "0.2.0-beta.9",
"io-ts": "2.1.3"
},
"devDependencies": {
"typescript": "4.7.4"
}
}

Install these dependencies with the following command:


$ npm install

Finally, create a new file named index.ts, where we'll define our API specification:

index.ts

import * as t from 'io-ts';
import { apiSpec, httpRoute, httpRequest } from '@api-ts/io-ts-http';
const GetHelloWorld = httpRoute({
path: '/hello/{name}',
method: 'GET',
request: httpRequest({
params: {
name: t.string,
},
}),
response: {
200: t.string,
},
});
export const API = apiSpec({
'api.v1.hello-world': {
get: GetHelloWorld,
},
});

Compile your API specification with:


$ npm run build