RESTful API

The @ginjou/with-rest-api package provides a flexible fetcher for connecting Ginjou to standard RESTful APIs. It is specifically designed to follow the conventions established by json-server.

Installation

Install the RESTful API provider and its peer dependency:

pnpm add @ginjou/with-rest-api

yarn add @ginjou/with-rest-api

npm install @ginjou/with-rest-api

bun add @ginjou/with-rest-api

Setup

To use the RESTful API provider, initialize the fetcher and register it in your root component.

Vue

In a Vue application, use defineFetchersContext within your App.vue setup.

<script setup lang="ts">
import { defineFetchersContext } from '@ginjou/vue'
import { createFetcher } from '@ginjou/with-rest-api'

defineFetchersContext({
    default: createFetcher({
        url: 'https://api.example.com'
    })
})
</script>

<template>
    <RouterView />
</template>

Nuxt

For Nuxt applications, register the provider in your root app.vue component.

<script setup lang="ts">
import { defineFetchersContext } from '@ginjou/vue'
import { createFetcher } from '@ginjou/with-rest-api'

defineFetchersContext({
    default: createFetcher({
        url: 'https://api.example.com'
    })
})
</script>

<template>
    <NuxtLayout>
        <NuxtPage />
    </NuxtLayout>
</template>

Fetcher Capability & Conventions

The createFetcher implementation relies on specific query parameters and header conventions common in the json-server ecosystem.

Pagination

The fetcher translates Ginjou's pagination state into _start and _end query parameters.

• _start: The zero-based index of the first item to return.
• _end: The zero-based index of the last item (exclusive).

Sorting

Sorting is handled via _sort and _order parameters.

• _sort: A comma-separated list of fields to sort by.
• _order: A comma-separated list of sort directions (asc or desc).

Filtering

Filters are mapped to query parameters using field suffixes: