@cocreators-ee/apity

📘️ apity - Typed API client for Svelte and SvelteKit

A typed fetch client for openapi-typescript compatible with SvelteKit's custom fetch

Installation

npm install @cocreators-ee/apity

Or

pnpm add @cocreators-ee/apity

Features

• Support of JSON request and responses from OpenAPI 3.0
• Support of {#await} syntax in Svelte templates
• Compatibility with SvelteKit's fetch in load functions
• Request reloading
• Configuration of default fetch options

On the roadmap:

• Caching of subsequent requests with the same URL and parameters

Usage

Generate typescript definition from schema

Before working with the library, you need to generate an API spec using openapi-typescript:

npx openapi-typescript https://petstore3.swagger.io/ --output petstore.ts

🚀 https://petstore3.swagger.io/api/v3/openapi.json → file:.petstore.ts [870ms]

Using Apity

Configure Apity instance and generate functions for making API calls:

// File: api.ts

import { Apity } from '@cocreators-ee/apity'
import { paths } from './petstore'

const apity = Apity.for<paths>()

// global configuration
apity.configure({
  // Base URL to your API, e.g. `/` if you're serving API from the same domain
  baseUrl: 'https://petstore.swagger.io/v2',
  // RequestInit options, e.g. default headers
  init: {
    // mode: 'cors'
    // headers: {}
  },
})

// create fetch operations
export const findPetsByStatus = apity
  .path('/pet/findByStatus')
  .method('get')
  .create()
export const addPet = apity.path('/pet').method('post').create()

Each API call is represented as a request object that has the following properties:

{
  // Svelte store that contains a promise for an API call.
  // If you reload the requets using reload() function, this store will be updated.
  ready,
  // Promise for the API call.
  // Useful for server code and places where you can't use the `ready` store.
  onData,
  // Svelte store containing the response of the API call.
  resp,
  // Function that reloads the request with the same parameteres.
  reload,
}

Each response is a Svelte store returning either an undefined, or the following object:

{
  // HTTP status code
  status,
  // Boolean, whether the request was successful or not
  ok,
  // Typed object for a successful request. Built from the OpenAPI spec
  data,
}

Using Apity with await syntax in templates

<script lang="ts">
  import { findPetByStatus } from './api.ts'
  const request = findPetByStatus({ status: 'sold' })
  const petsReady = request.ready
</script>

<div>
  {#await $petsReady}
    <p>Loading..</p>
  {:then resp}
    {#if resp.ok}
      {#each resp.data as pet}
        <p>{pet.name}</p>
      {/each}
    {:else}
      <p>Error while loading pets</p>
    {/if}
  {/await}

  <button on:click={() => {request.reload()}}>
    Reload pets
  </button>
</div>

Subscribing to response store

<script lang="ts">
  import { findPetByStatus } from './api.ts'
  const request = findPetByStatus({ status: 'sold' })
  let names = []

  request.resp.subscribe(resp => {
    if (resp.ok) {
      names = resp.data.map(pet => pet.name)
    }
  })
</script>

<div>
  {#each names as name}
    <p>{name}</p>
  {/each}
</div>

Using in load functions

Fetch operations support SvelteKit's load function from +page.ts and +page.server.ts:

export async function load({ fetch }) {
  const request = findPetByStatus({ status: 'sold' })
  const resp = await request.onData
  // returning the entire request to a page in order to be able to `reload()` it.
  // `request.resp.data` is already available
  return { request }
}