Our types package provides a framework that makes it faster to develop and safer to maintain applications written in TypeScript.

Typed paths for each Data8 web service endpoint enable requests and responses to be checked at compile time, catching mistakes before they reach production. IntelliSense autocomplete for endpoints, request bodies and response shapes increases development speed.

By default, our types package ships only TypeScript type definitions. To turn these types into fully-typed autocompleted API calls, pair the package with openapi-fetch, a client that reads a service's paths and infers the request and response body.

npm install @data8/types openapi-fetch

Creating a Client

Each Data8 web service ships as its own namespace in @data8/types. To call one, import the service name from the types package and pass its paths type to openapi-fetch's createClient, along with the base URL for the API call, in this case https://webservices.data-8.co.uk. This gives you a fully-typed client with IntelliSense for every endpoint, request body and response. This can be used across any TypeScript project, as seen in the Data8 TypeScript demo, which uses both Vue.js and React.

import { EmailValidation } from "@data8/types";
import createClient from "openapi-fetch";

const emailClient = createClient<EmailValidation.paths>({
  baseUrl: "https://webservices.data-8.co.uk",
});

The paths type is what links the client to the service's endpoints. Replace EmailValidation with any other service. Find the import name of each service, along with its available endpoints, below.

Sending a Request

The openapi-fetch client can be used to send requests and handle responses. To do this, data is posted to the client, with an endpoint, in the format client.POST("/ServiceName/Endpoint.json").

Using this format, every request returns { data, error }. An HTTP 200 response from the API populates data, and error is undefined. Any non-200 status - for example an invalid API key - returns error and data is undefined. Both scenarios should be handled.

A 200 response only means the request reached the service, not that the operation succeeded. Therefore, business/validation failures - e.g., a missing email address - should be handled by checking for data.Status.Success.

Since the client was created with ServiceName.paths, attaching the endpoint to it type-checks the body and returned data and enables IntelliSense.

// In production this value should be swapped for an environment variable
const API_KEY = "your_api_key";
async function validateEmail(email: string, fullName: string) {
  const name = toNameRecord(fullName);
  const { data, error } = await emailClient.POST("/EmailValidation/Cleanse.json", {
    headers: { "content-type": "application/json" },
    body: {
      username: "apikey-" + API_KEY,
      email,
      level: "Address",
      record: name ? { Name: name } : undefined,
      options: {
        ParseName: true,
        OutputNameCheck: true,
      },
    },
  });

  if (error) throw new Error(JSON.stringify(error));
  if (!data?.Status?.Success) throw new Error(data?.Status?.ErrorMessage ?? "Data8 request failed");
  return data;
}

To use the sample code, you'll need to get your own API key from your dashboard.

Components

As well as paths, each service has a components type containing reusable schemas from its API. You can reference these using Service.components["schemas"]["SchemaName"] to type values you build yourself, before making a request.

The example below uses this to type a helper that takes a plain name string and returns a Name object. By annotating the return type as EmailValidation.components["schemas"]["Name"], TypeScript checks the object's shape as you build it and offers autocomplete for its fields:

function toNameRecord(fullName: string): EmailValidation.components["schemas"]["Name"] | undefined {
  const trimmed = fullName.trim();
  if (!trimmed) return undefined;

  const parts = trimmed.split(/\s+/);
  if (parts.length === 1) {
    return { Forename: parts[0] };
  }

  return {
    Forename: parts[0],
    Surname: parts.slice(1).join(" "),
  };
}

Accessing the type of a result

There are two ways to access the type of a result. First by directly accessing it with components:

EmailValidation.components["schemas"]["EmailCleanseOutput"]

Alternatively, you can return the type from your own request function: Awaited<ReturnType<typeof yourRequest>>.

type ValidationResult = Awaited<ReturnType<typeof validateEmail>>;