REST

Introduction

REST implementation provides multiple dependencies implementations to support read/write interactions with JSON REST data sources.

Implementations

makeJsonRestAdapter

This implementation of the adapter will execute context through HTTP requests using the fetch API.

makeJsonRestAdapter and makeRestAdapterWith use makeHttpAdapterWith.

Usage

import { paramsSerializer } from '@foscia/http';
import { makeRestAdapterWith, makeJsonRestAdapter } from '@foscia/rest';

// Using blueprint (preconfigured with sensible defaults).
const { adapter } = makeJsonRestAdapter({
  /* ...configuration */
});
// Using constructor (no default configuration provided).
const { adapter } = makeRestAdapterWith({
  serializeParams: paramsSerializer,
  /* ...configuration */
});

const response = await adapter.execute({
  /* ...context */
});

Configuration

makeJsonRestAdapter and makeRestAdapterWith extend its configuration object from:

• makeHttpAdapter

Name	Type	Description
includeParamKey	string | null	Define the query parameter to append when relationships inclusion is requested through include. Default to include.

Defined in

• packages/rest/src/blueprints/makeJsonRestAdapter.ts
• packages/rest/src/makeRestAdapterWith.ts

makeJsonRestDeserializer

This implementation of the deserializer extract model instances from object documents.

makeJsonRestDeserializer extends the makeDeserializerWith.

Deserialized REST document example

Here is an example of a REST document which makeJsonRestDeserializer can deserialize to model instances.

[
  {
    "id": "1",
    "title": "Foo",
    "body": "Foo Body",
    "publishedAt": "2023-10-24T10:00:00.000Z",
    "comments": [
      {
        "id": "1",
        "body": "Foo Comment"
      },
      {
        "id": "2",
        "body": "Bar Comment"
      }
    ]
  },
  {
    "type": "posts",
    "id": "2",
    "title": "Bar",
    "body": "Bar Body",
    "publishedAt": null,
    "comments": []
  }
]

Usage

import { makeJsonRestDeserializer } from '@foscia/rest';

// Using blueprint (preconfigured with sensible defaults).
const { deserializer } = makeJsonRestDeserializer({
  /* ...configuration */
});

const { instances } = await deserializer.deserialize(data, {
  /* ...context */
});

Configuration

makeJsonRestDeserializer extends its configuration object from:

• makeDeserializerWith

Name	Type	Description
pullIdentifier	(record: Record, context: {}) => Awaitable<DeserializerRecordIdentifier>	Extract identifier (type and ID) from record.
pullAttribute	(record: Record, deserializerContext: DeserializerContext, extract: Extract) => Awaitable<unknown>	Extract raw attribute value from record.
pullAttribute	(record: Record, deserializerContext: DeserializerContext, extract: Extract) => Awaitable<Arrayable<Record> | null | undefined>	Extract raw relation value from record.

Defined in

• packages/rest/src/blueprints/makeJsonRestDeserializer.ts

makeJsonRestSerializer

This implementation of the serializer creates a REST documents from model instance and relations.

makeJsonRestSerializer extends the makeSerializerWith.

Serialized REST document example

Here is an example of a REST document which makeJsonRestSerializer can create from a model instance.

{
  "id": "1",
  "title": "Foo",
  "body": "Foo Body",
  "publishedAt": "2023-10-24T10:00:00.000Z",
  "comments": ["1", "2"]
}

Usage

import { makeJsonRestSerializer } from '@foscia/rest';

// Using blueprint (preconfigured with sensible defaults).
const { serializer } = makeJsonRestSerializer({
  /* ...configuration */
});

const data = await serializer.serializeInstance(instance, {
  /* ...context */
});

Configuration

makeJsonRestSerializer extends its configuration object from:

• makeSerializerWith

Name	Type	Description
serializeType	boolean	Append the instance type to the serialized object.

Defined in

packages/rest/src/blueprints/makeJsonRestSerializer.ts