Skip to main content

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:

NameTypeDescription
includeParamKeystring | nullDefine the query parameter to append when relationships inclusion is requested through include. Default to include.

Defined in​

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:

NameTypeDescription
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​

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:

NameTypeDescription
serializeTypebooleanAppend the instance type to the serialized object.

Defined in​

packages/rest/src/blueprints/makeJsonRestSerializer.ts