aspida

aspida	aspida-mock	openapi2aspida	pathpida	@aspida/axios	@aspida/ky	@aspida/fetch

TypeScript friendly HTTP client wrapper for the browser and node.js.

🇺🇸English | 🇯🇵日本語

Fetures

• Path, URL query, header, body, and response can all specify the type
• FormData / URLSearchParams content can also specify the type
• HTTP client supports axios / ky / ky-universal / fetch
• Path definition is the same naming convention as Nuxt.js pages

Procedure

1. Reproduce the endpoint directory structure in the apis directory
2. Export Methods interface with TS file
3. Call 'aspida --build' with npm scripts
4. API type definition file 'apis/$api.ts' will be generated, so import the application and make an HTTP request

Getting Started

Installation (axios ver.)

• Using npm:

  $ npm install @aspida/axios axios
  

• Using Yarn:

  $ yarn add @aspida/axios axios
  

Create apis directory

$ mkdir apis

Create an endpoint type definition file

• GET: /v1/users/?limit={number}

• POST: /v1/users

  apis/v1/users/index.ts

  interface User {
    id: number
    name: string
  }
  
  export interface Methods {
    get: {
      query?: {
        limit: number
      }
  
      resBody: User[]
    }
  
    post: {
      reqBody: {
        name: string
      }
  
      resBody: User
    }
  }
  

• GET: /v1/users/${userId}

• PUT: /v1/users/${userId}

  apis/v1/users/[e-mail]

  Specify the type of path variable “userId” starting with underscore with “@number”
  If not specified with @, the default path variable type is "number | string"

  interface User {
    id: number
    name: string
  }
  
  export interface Methods {
    get: {
      resBody: User
    }
  
    put: {
      reqBody: {
        name: string
      }
  
      resBody: User
    }
  }
  

Build type definition file

package.json

{
  "scripts": {
    "api:build": "aspida --build"
  }
}

$ npm run api:build

> apis/$api.ts was built successfully.

Make HTTP request from application

src/index.ts

import aspida from "@aspida/axios"
import api from "../apis/$api"
;(async () => {
  const userId = 0
  const limit = 10
  const client = api(aspida())

  await client.v1.users.post({ data: { name: "taro" } })

  const res = await client.v1.users.get({ query: { limit } })
  console.log(res)
  // req -> GET: /v1/users/?limit=10
  // res -> { status: 200, data: [{ id: 0, name: 'taro' }], headers: {...} }

  const user = await client.v1.users._userId(userId).$get()
  console.log(user)
  // req -> GET: /v1/users/0
  // res -> { id: 0, name: 'taro' }
})()

Learn more about HTTP clients

• aspida-axios
• aspida-ky
• aspida-fetch

Tips

Change the directory where type definition file is placed to other than apis

Create a configuration file at the root of the project

aspida.config.js

module.exports = { input: "src" }

Specify baseURL in configuration file

module.exports = { input: "apis", baseURL: "https://example.com/api" }

If you want to define multiple API endpoints, specify them in an array

module.exports = [{ input: "api1" }, { input: "api2", baseURL: "https://example.com/api" }]

POST with FormData

apis/v1/users/index.ts

export interface Methods {
  post: {
    reqFormat: FormData

    reqBody: {
      name: string
      icon: ArrayBuffer
    }

    resBody: {
      id: number
      name: string
    }
  }
}

src/index.ts

import aspida from "@aspida/axios"
import api from "../apis/$api"
;(async () => {
  const userId = 0
  const limit = 10
  const client = api(aspida())
  const iconImage = imageBuffer

  const user = await client.v1.users.$post({
    data: {
      name: "taro",
      icon: iconImage
    }
  })
  console.log(user)
  // req -> POST: h/v1/users/0
  // res -> { id: 0, name: 'taro' }
})()

POST with URLSearchParams

apis/v1/users/index.ts

export interface Methods {
  post: {
    reqFormat: URLSearchParams

    reqBody: {
      name: string
    }

    resBody: {
      id: number
      name: string
    }
  }
}

src/index.ts

import aspida from "@aspida/axios"
import api from "../apis/$api"
;(async () => {
  const userId = 0
  const limit = 10
  const client = api(aspida())

  const user = await client.v1.users.$post({ data: { name: "taro" } })
  console.log(user)
  // req -> POST: /v1/users/0
  // res -> { id: 0, name: 'taro' }
})()

Receive response with ArrayBuffer

apis/v1/users/index.ts

export interface Methods {
  get: {
    query: {
      name: string
    }

    resBody: ArrayBuffer
  }
}

src/index.ts

import aspida from "@aspida/axios"
import api from "../apis/$api"
;(async () => {
  const userId = 0
  const limit = 10
  const client = api(aspida())

  const user = await client.v1.users.$get({ query: { name: "taro" } })
  console.log(user)
  // req -> POST: /v1/users/0
  // res -> ArrayBuffer
})()

License

aspida is licensed under a MIT License.