---
url: https://canary.warp-drive.io/api/@warp-drive/utilities/json-api.md
description: >-
  Request builders and cache serializers for JSON:API servers, with dasherized
  plural URLs and configurable `Accept` headers.
---

This module provides utilities for working with [{json:api}](https://jsonapi.org) APIs with ***Warp*Drive**

## Usage

Request builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
They take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.
See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and when to use one.

For instance, to fetch a resource from your API

::: code-group

```ts [input.ts]
import { findRecord } from '@warp-drive/utilities/json-api';
import type { EmberDeveloper } from '#/data/types';

const options = findRecord<EmberDeveloper>(
 'ember-developer', '1',
 { include: ['pets', 'friends']
});
```

```ts [output.ts]
{
  url: 'https://api.example.com/v1/ember-developers/1?include=friends,pets',
  method: 'GET',
  headers: <Headers>,
    // => 'Accept': 'application/vnd.api+json'
    // => 'Content-Type': 'application/vnd.api+json'
  op: 'findRecord';
  records: [{ type: 'ember-developer', id: '1' }]
}
```

:::

Request builder output may be used with either [RequestManager.request](../../core/classes/RequestManager.md#request) or Store.request.

```ts
const data = await store.request(options);
```

### Features

* URLs are stable. The same query will produce the same URL every time, even if the order of keys in
  the query or values in an array changes.
* URLs follow the most common {json:api} format (dasherized pluralized resource types)
* The response document's `errors` are typed as `ApiError`, the
  [{json:api} error object](https://jsonapi.org/format/#error-objects).

## Functions

* [createRecord](functions/createRecord.md)
* [deleteRecord](functions/deleteRecord.md)
* [findRecord](functions/findRecord.md)
* [postQuery](functions/postQuery.md)
* [query](functions/query.md)
* [serializePatch](functions/serializePatch.md)
* [serializeResources](functions/serializeResources.md)
* [setBuildURLConfig](functions/setBuildURLConfig.md)
* [updateRecord](functions/updateRecord.md)

## Types

* [JSONAPIConfig](types/JSONAPIConfig.md)
* [JsonApiResourcePatch](types/JsonApiResourcePatch.md)