JsonApiClient

Defined in: packages/json-api-client/src/JsonApiClient.ts:31

JSON:API Client class provides functionality specific to JSON:API server.

See

• JsonApiClientOptions
• BaseUrl

Extends

• ApiClient

Constructors

Constructor

new JsonApiClient(baseUrl, options?): JsonApiClient;

Defined in: packages/json-api-client/src/JsonApiClient.ts:57

Creates a new instance of the JsonApiClient.

Parameters

baseUrl

string

The base URL of the API. BaseUrl

options?

JsonApiClientOptions

(Optional) Additional options for configuring the API client. JsonApiClientOptions

Returns

JsonApiClient

Overrides

ApiClient.constructor

Properties

apiPrefix

apiPrefix: string | undefined;

Defined in: packages/api-client/dist/index.d.mts:216

ApiClientOptions.apiPrefix

Inherited from

ApiClient.apiPrefix

---

authentication

authentication: Authentication | undefined;

Defined in: packages/api-client/dist/index.d.mts:224

ApiClientOptions.authentication

Inherited from

ApiClient.authentication

---

baseUrl

baseUrl: string;

Defined in: packages/api-client/dist/index.d.mts:212

BaseUrl

Inherited from

ApiClient.baseUrl

---

cache

cache: Cache | undefined;

Defined in: packages/api-client/dist/index.d.mts:232

ApiClientOptions.cache

Inherited from

ApiClient.cache

---

customFetch

customFetch:
  | ((input, init?) => Promise<Response>)
  | undefined;

Defined in: packages/api-client/dist/index.d.mts:220

ApiClientOptions.customFetch

Inherited from

ApiClient.customFetch

---

debug

debug: boolean | undefined;

Defined in: packages/api-client/dist/index.d.mts:244

ApiClientOptions.debug

Inherited from

ApiClient.debug

---

decoupledRouterApiPrefix

decoupledRouterApiPrefix: string | undefined;

Defined in: packages/json-api-client/src/JsonApiClient.ts:45

See

JsonApiClientOptions.decoupledRouterApiPrefix

---

defaultLocale

defaultLocale: string | undefined;

Defined in: packages/api-client/dist/index.d.mts:228

ApiClientOptions.defaultLocale

Inherited from

ApiClient.defaultLocale

---

indexLookup

indexLookup: boolean | undefined;

Defined in: packages/json-api-client/src/JsonApiClient.ts:40

See

JsonApiClientOptions.indexLookup

---

languagePathPrefix

languagePathPrefix: boolean;

Defined in: packages/json-api-client/src/JsonApiClient.ts:50

See

JsonApiClientOptions.languagePathPrefix

---

logger

logger:
  | {
  debug?: LogMethod;
  error?: LogMethod;
  http?: LogMethod;
  info?: LogMethod;
  silly?: LogMethod;
  verbose?: LogMethod;
  warn?: LogMethod;
}
  | undefined;

Defined in: packages/api-client/dist/index.d.mts:240

ApiClientOptions.logger

Inherited from

ApiClient.logger

---

router

router: DecoupledRouterClient;

Defined in: packages/json-api-client/src/JsonApiClient.ts:35

link DecoupledRouterClient

---

serializer

serializer: Serializer | undefined;

Defined in: packages/api-client/dist/index.d.mts:236

ApiClientOptions.serializer

Inherited from

ApiClient.serializer

Methods

addAuthorizationHeader()

addAuthorizationHeader(options): Promise<RequestInit>;

Defined in: packages/api-client/dist/index.d.mts:274

Adds an authorization header to the provided RequestInit options if authentication of type “Basic” is configured. If the authentication type is “OAuth”, it will fetch a new access token or use the stored access token if it exists and is still valid. if the authentication type is “Custom”, it will use the provided value.

Parameters

options

RequestInit | undefined

The RequestInit options to which the authorization header should be added.

Returns

Promise<RequestInit>

The updated RequestInit options with the authorization header, if applicable.

Inherited from

ApiClient.addAuthorizationHeader

---

createResource()

createResource<T>(
   type,
   body,
   options?): Promise<
  | T
| RawApiResponseWithData<T>>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:781

Create a resource of the specified type using the provided body.

Type Parameters

T

T

Parameters

type

string

The type of the entity with bundle information.

body

string | object

The body of the request.

options?

CreateOptions

(Optional) Additional options for customizing the request. CreateOptions

Returns

Promise< | T | RawApiResponseWithData<T>>

A Promise that resolves to a Response object or RawApiResponseWithData.

Remarks

This method initiates the creation of a resource by sending a POST request to the API.

Example

const responseBody = await createResource("node--page", `{
  "data": {
    "type": "node--page",
    "attributes": {
      "title": "My custom title",
      "body": {
        "value": "Custom value",
        "format": "plain_text"
      }
    }
  }
}, { rawResponse: false });

---

createTranslation()

createTranslation<T>(
   type,
   resourceId,
   body,
   options?): Promise<
  | T
| RawApiResponseWithData<T>>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:870

Creates a new translation of an existing resource.

Unlike createResource (a collection POST that creates a new entity), this POSTs to the individual resource path with langCode to add a translation in the language given by locale. Requires a backend that supports creating a translation on the individual path (the jsonapi_multilingual module / core issue #3199697): the payload’s langcode attribute, if present, must match locale, and a translation that already exists is rejected as a 409 conflict.

Type Parameters

T

T

Parameters

type

string

The type of the entity with bundle information.

resourceId

string

The ID of the entity to add a translation to.

body

string | object

The body of the request.

options?

CreateOptions

(Optional) Additional options; locale is the target language. CreateOptions

Returns

Promise< | T | RawApiResponseWithData<T>>

A Promise that resolves to a Response object or RawApiResponseWithData.

Example

const responseBody = await createTranslation("node--page", "7cbb8b73-8bcb-4008-874e-2bd496bd419d", body, { locale: "de" });

---

createURL()

createURL(__namedParameters): Promise<string>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:308

Generates an endpoint URL based on the provided parameters.

Parameters

__namedParameters

EndpointUrlSegments

Returns

Promise<string>

The endpoint URL as a string.

Params

params - The parameters to use for creating the URL. EndpointUrlSegments

---

deleteResource()

deleteResource<T>(
   type,
   resourceId,
   options?): Promise<
  | T
| RawApiResponseWithData<T>>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:403

Deletes a resource of the specified type using the provided resource ID.

Type Parameters

T

T

Parameters

type

string

The type of the entity with bundle information.

resourceId

string

The ID of the resource to be deleted.

options?

DeleteOptions

(Optional) Additional options for customizing the request. DeleteOptions

Returns

Promise< | T | RawApiResponseWithData<T>>

A Promise that resolves to a Response object or RawApiResponseWithData.

Example

const responseBody = await deleteResource("node--page", "7cbb8b73-8bcb-4008-874e-2bd496bd419d", { rawResponse: false });

---

fetch()

fetch(input, init?): Promise<FetchReturn>;

Defined in: packages/api-client/dist/index.d.mts:257

Uses customFetch if it is set, otherwise uses the default fetch

Parameters

input

URL | RequestInfo

RequestInfo

init?

RequestInit

RequestInit

Returns

Promise<FetchReturn>

a response wrapped in a promise

Inherited from

ApiClient.fetch

---

getAccessToken()

protected getAccessToken(__namedParameters): Promise<OAuthTokenResponse>;

Defined in: packages/api-client/dist/index.d.mts:262

Fetch the OAuth token from the BaseUrl

Parameters

__namedParameters

OAuthCredentials

Returns

Promise<OAuthTokenResponse>

Params

params - The credentials for getting an OAuth token. OAuthCredentials

Inherited from

ApiClient.getAccessToken

---

getCachedResponse()

getCachedResponse<T>(cacheKey): Promise<
  | NonNullable<Awaited<T>>
| null>;

Defined in: packages/api-client/dist/index.d.mts:286

Retrieves a cached response from the cache.

Type Parameters

T

T

Parameters

cacheKey

string

The cache key to use for retrieving the cached response.

Returns

Promise< | NonNullable<Awaited<T>> | null>

A promise wrapping the cached response as a generic type.

Inherited from

ApiClient.getCachedResponse

---

getCollection()

getCollection<T>(type, options?): Promise<
  | T
| RawApiResponseWithData<T>>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:152

Retrieves a collection of data of a specific entity type and bundle from the JSON:API.

Type Parameters

T

T

Parameters

type

string

The type of resource to retrieve, in the format “entityType—bundle”. For example, “node—page”. EntityTypeWithBundle

options?

GetOptions

(Optional) Additional options for customizing the request. GetOptions

Returns

Promise< | T | RawApiResponseWithData<T>>

A Promise that resolves to the JSON data of the requested resource.

Example

Using JSONAPI.CollectionResourceDoc type from the jsonapi-typescript package

const collection = await jsonApiClient.get<JSONAPI.CollectionResourceDoc<string, Recipe>>("node--recipe");

---

getResource()

getResource<T>(
   type,
   resourceId,
   options?): Promise<
  | T
| RawApiResponseWithData<T>>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:233

Retrieves data for a resource by ID of a specific entity type and bundle from the JSON:API.

Type Parameters

T

T

Parameters

type

string

The type of resource to retrieve, often in the format “entityType—bundle”, but may be rewritten as a single string.

resourceId

string

The ID of the individual resource to retrieve.

options?

GetOptions

(Optional) Additional options for customizing the request. GetOptions

Returns

Promise< | T | RawApiResponseWithData<T>>

A Promise that resolves to the JSON data of the requested resource.

Example

Using JSONAPI.CollectionResourceDoc type from the jsonapi-typescript package

const collection = await jsonApiClient.get<JSONAPI.CollectionResourceDoc<string, Recipe>>("node--recipe");

---

getResourceByPath()

getResourceByPath(path, options?): Promise<unknown>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:620

Attempts to resolve a path to a resource and then fetches the resolved resource.

Parameters

path

string

The path to resolve and fetch.

options?

GetOptions

(Optional) Additional options for customizing the request. GetOptions

Returns

Promise<unknown>

• A promise that resolves to either the JSON data of the requested resource or an UnResolvedPath if the path could not be resolved.

Example

const article = await jsonApiClient.getResourceByPath("/articles/give-it-a-go-and-grow-your-own-herbs");

---

getView()

getView<T>(type, options?): Promise<
  | T
| RawApiResponseWithData<T>>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:544

Retrieves a collection of data of a specific view display via JSON:API views. Requires that the jsonapi_views module is enabled on your Drupal site.

Type Parameters

T

T

Parameters

type

string

The type of resource to retrieve, in the format “name—display_id”. For example, “content—page_1”.

options?

GetOptions

(Optional) Additional options for customizing the request. GetOptions

Returns

Promise< | T | RawApiResponseWithData<T>>

A Promise that resolves to the JSON data of the requested collection.

Example

Using JSONAPI.CollectionResourceDoc type from the jsonapi-typescript package

const view = await jsonApiClient.getView<JSONAPI.CollectionResourceDoc<string, Recipe>>("recipes--page_1");

---

log()

log(level, message): void;

Defined in: packages/api-client/dist/index.d.mts:280

Calls the appropriate logger method based on level

Parameters

level

LogLevels

level based on npm log levels

message

string

the message to log

Returns

void

Inherited from

ApiClient.log

---

processApiResponseAndParseBody()

processApiResponseAndParseBody<T>(
   response,
   cacheKey,
options?): Promise<string | T>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:952

Processes the API response and returns the JSON data.

Type Parameters

T

T

Parameters

response

Response

The response object from the API.

cacheKey

string

The cache key to use for caching the response.

options?

| GetOptions | UpdateOptions | CreateOptions

(Optional) Additional options for customizing the request. UpdateOptions | CreateOptions

Returns

Promise<string | T>

---

resolveLanguage()

protected resolveLanguage(locale?): object;

Defined in: packages/json-api-client/src/JsonApiClient.ts:101

Resolves how the targeted language is carried on the wire.

The language is sent twice so the same request works whether the backend selects a translation by URL prefix (stock Drupal, which ignores langCode) or by the langCode query parameter (the jsonapi_multilingual module, whose only language selector is langCode): as the /{locale}/ path prefix (disable via languagePathPrefix: false, recommended for jsonapi_multilingual backends) and as langCode.

Parameters

locale?

string

The target language, or undefined for none.

Returns

object

The path prefix and langCode to apply, each present only when it should be sent.

langCode?

optional langCode?: string;

prefix?

optional prefix?: string;

---

updateResource()

updateResource<T>(
   type,
   resourceId,
   body,
   options?): Promise<
  | T
| RawApiResponseWithData<T>>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:678

Updates a resource of the specified type using the provided resource ID.

Type Parameters

T

T

Parameters

type

string

The type of the entity with bundle information.

resourceId

string

The ID of the resource to be updated.

body

string | object

The body of the request.

options?

UpdateOptions

(Optional) Additional options for customizing the request. UpdateOptions

Returns

Promise< | T | RawApiResponseWithData<T>>

A Promise that resolves to a Response object or RawApiResponseWithData.

Remarks

This method initiates the update of a resource by sending a PATCH request to the API.

Example

const responseBody = await updateResource("node--page", "7cbb8b73-8bcb-4008-874e-2bd496bd419d", `{
       "data": {
        "type": "node--page",
        "id": "11fc449b-aca0-4b74-bc3b-677da021f1d7",
        "attributes": {
            "drupal_internal__nid": 2,
            "drupal_internal__vid": 3,
            "langcode": "en",
            "revision_log": null,
            "status": true,
            "title": "test 2"
        }
    }
}`, { rawResponse: false });

---

createCacheKey()

static createCacheKey(__namedParameters): Promise<string>;

Defined in: packages/json-api-client/src/JsonApiClient.ts:495

Generates a cache key based on the provided parameters. If the cacheKey parameter is provided, it will be used as the cache key.

Parameters

__namedParameters

EndpointUrlSegments

Returns

Promise<string>

A promise wrapping the generated cache key as a string.

Params

params - The parameters to use for generating the cache key. EndpointUrlSegments

Examples

// Generate a cache key with entityTypeId and bundleId only
const key1 = await MyClass.createCacheKey('entity1', 'bundle1');
// key1: 'entity1--bundle1'

// Generate a cache key with entityTypeId, bundleId, localeSegment, and queryString
const key2 = await MyClass.createCacheKey('entity2', 'bundle2', 'en-US', 'param1=value1&param2=value2');
// key2: 'en-US--entity2--bundle2--<sha256_hash_of_query_string>'

---

getEntityTypeIdAndBundleId()

static getEntityTypeIdAndBundleId(type): object;

Defined in: packages/json-api-client/src/JsonApiClient.ts:468

Parameters

type

string

Returns

object

bundleId

bundleId: string;

entityTypeId

entityTypeId: string;

---

languageQuery()

protected static languageQuery(
   queryString?,
   langCode?,
   includeFallback?): string | undefined;

Defined in: packages/json-api-client/src/JsonApiClient.ts:125

Merges the language-selection query parameters into a caller-supplied query string. langCode targets one translation; includeFallback=1 defers a missing translation to the site’s language fallback chain and is only valid alongside langCode, so it is dropped without one.

Parameters

queryString?

string

The caller-supplied query string, if any.

langCode?

string

The language to target, if any.

includeFallback?

boolean

Whether to opt into server-side fallback.

Returns

string | undefined

The combined query string, or undefined when empty.