aspida

aspida	aspida-mock	openapi2aspida	pathpida

@aspida/axios	@aspida/ky	@aspida/fetch	@aspida/node-fetch

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

🇺🇸English | 🇯🇵日本語

Features

• 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 / node-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 a Type alias named "Methods"
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

  type User = {
    id: number
    name: string
  }
  
  export type 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"

  type User = {
    id: number
    name: string
  }
  
  export type 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' }
})()

Read more posts by DEV Community

aspida - DEV Community

Learn more about HTTP clients

• aspida-axios
• aspida-ky
• aspida-fetch
• aspida-node-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" }]

Serialize GET parameters manually

aspida leaves GET parameter serialization to standard HTTP client behavior
If you want to serialize manually, you can use config object of HTTP client

src/index.ts

import axios from "axios"
import qs from "qs"
import aspida from "@aspida/axios"
import api from "../apis/$api"
;(async () => {
  const client = api(
    aspida(axios, { paramsSerializer: params => qs.stringify(params, { indices: false }) })
  )

  const users = await client.v1.users.$get({
    // config: { paramsSerializer: (params) => qs.stringify(params, { indices: false }) },
    query: { ids: [1, 2, 3] }
  })
  console.log(users)
  // req -> GET: /v1/users/?ids=1&ids=2&ids=3
  // res -> [{ id: 1, name: 'taro1' }, { id: 2, name: 'taro2' }, { id: 3, name: 'taro3' }]
})()

POST with FormData

apis/v1/users/index.ts

export type 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 client = api(aspida())

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

POST with URLSearchParams

apis/v1/users/index.ts

export type 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 client = api(aspida())

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

Receive response with ArrayBuffer

apis/v1/users/index.ts

export type Methods = {
  get: {
    query: {
      name: string
    }

    resBody: ArrayBuffer
  }
}

src/index.ts

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

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

License

aspida is licensed under a MIT License.