aspida

🇺🇸English | 🇯🇵日本語

aspida

Type safe HTTP client wrapper for the browser and node.js.

Fetures

• Path, URL query, header, body, and response can all be type safe
• FormData / URLSearchParams content can also be type safe
• 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 @aspida/axios
  

• Using Yarn:

  $ yarn add  aspida axios @aspida/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
      }
  
      resData: User[]
    }
  
    post: {
      reqData: {
        name: string
      }
  
      resData: 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: {
      resData: User
    }
  
    put: {
      reqData: {
        name: string
      }
  
      resData: 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 baseURL = "http://localhost:8080/api"
  const client = api(aspida(), baseURL)

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

  const res = await client.v1.users.get({ query: { limit } })
  console.log(res)
  // req -> GET: http://localhost:8080/api/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: http://localhost:8080/api/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: {
    reqType: FormData

    reqData: {
      name: string
      icon: ArrayBuffer
    }

    resData: {
      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 baseURL = "http://localhost:8080/api"
  const client = api(aspida(), baseURL)
  const iconImage = imageBuffer

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

POST with URLSearchParams

apis/v1/users/index.ts

export interface Methods {
  post: {
    reqType: URLSearchParams

    reqData: {
      name: string
    }

    resData: {
      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 baseURL = "http://localhost:8080/api"
  const client = api(aspida(), baseURL)

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

Receive response with ArrayBuffer

apis/v1/users/index.ts

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

    resData: ArrayBuffer
  }
}

src/index.ts

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

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

License

Aspida is licensed under a MIT License.