🌩 API Standards – Client

This library is based on tectonique/api-standards 🔗.

It provides client utilities to make API requests and error handling 100% type safe.

Currently, type wrappers are provided for:

• axios 🔗

📖 Table of contents

• 🌩 API Standards – Client
• 📖 Table of contents
• 📦 NPM Package
• 💾 Installation
• 🏁 Goal
• 📑 Documentation
  • 💠 Axios with type safety
• 📜 Changelog
• 🦔 Author

📦 NPM Package

💾 Installation

Using npm:

npm i @tectonique/api-standards-client

Using yarn:

yarn add @tectonique/api-standards-client

🏁 Goal

When you have

• a type safe backend setup using tectonique/api-standards 🔗 or tectonique/api-standards 🔗,
• an exposed ProblemDetailsSuperType
• and this library installed you can create e.g. fully typed axios instances with error/Problem Detail handling!

You want to perform such 100% type safe API calls:

const createUserEnvelope = await MyApi.createUser(
  "[email protected]",
  "Theo Tester"
).catch(createProblemDetailHandler(pd => {
  if (createUserEnvelope.type === "response-not-an-envelope") {
    alert("Response is not an envelope!");
  }
}));

console.log("User id: ", createUserEnvelope.payload.id);

📑 Documentation

💠 Axios with type safety

• Import your backend request/query/response types.
• Import your backend Problem Detail Super Type.
• Create a typable axios instance with makeAxiosTypeSafe(axiosInstance).
• Create your custom API instance with methods that use get|post|put|patch|delete of the typeable axios instance.

An example: Here is an example:

import axios from "axios";
import { ProblemDetailSuperType } from "@backend/ProblemDetailSuperType"
import { createTypeSafeAxios, ClientProblemDetailSuperType } from "@tectonique/api-standards-client";

type Create_User_Body = {
  email: string;
  name: string;
};

type Create_User_Response = {
  id: string;
};

const {
  verbs,
  createProblemDetailHandler,
  handleProblemDetail
} = createTypeSafeAxios<ProblemDetailSuperType | ClientProblemDetailSuperType>(axios);

const MyApi = {
  createUser: (email: string, name: string) =>
    verbs.post<Create_User_Response, Create_User_Body, undefined>(
      "/users",
      { email, name }
    ),
};

const createUserEnvelope = await MyApi.createUser(
  "[email protected]",
  "Theo Tester"
).catch(createProblemDetailHandler(pd => {
  if (createUserEnvelope.type === "response-not-an-envelope") {
    alert("Response is not an envelope!");
  }
}));

console.log("User id: ", createUserEnvelope.payload.id);

// OR wit try catch + await
try {
  const createUserEnvelope = await MyApi.createUser(
    "[email protected]",
    "Theo Tester"
  )

  console.log("User id: ", createUserEnvelope.payload.id);
} catch ( error ) {
  // await is important to catch rethrown non problem detail errors!
  await handleProblemDetail(error, (pd) => {
    if (createUserEnvelope.type === "response-not-an-envelope") {
      alert("Response is not an envelope!");
    }
  })  
}

📜 Changelog

🦔 Author