djp

drupal-jsonapi-params

A package to manage json-api params

Showing:

Popularity

Downloads/wk

803

GitHub Stars

17

Maintenance

Last Commit

3mos ago

Contributors

7

Package

Dependencies

1

License

ISC

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

Drupal JSON-API Params

Build Status codecov npm npm bundle size npm type definitions npm downloads Known Vulnerabilities

The JSON:API is now part of Drupal Core.

The JSON:API specifications defines standard query parameters to be used to do filtering, sorting, restricting fields that are returned, pagination and so on.

This module provides a helper Class to create the required query. While doing so, it also tries to optimise the query by using the short form, whenever possible.

API Reference

Installation

Install the package via npm:

$ npm i drupal-jsonapi-params

Usage

import

Import DrupalJsonApiParams from drupal-jsonapi-params

import {DrupalJsonApiParams} from 'drupal-jsonapi-params';

const apiParams = new DrupalJsonApiParams();

require

var drupalJsonapiParams = require("drupal-jsonapi-params")

const apiParams = new drupalJsonapiParams.DrupalJsonApiParams();
apiParams
  // Add Group within Groups.
  .addGroup('publish_status', 'OR', 'parent_group')
  .addGroup('child_group_B', 'AND', 'parent_group')
  .addGroup('parent_group', 'AND')
  // Add Filters.
  .addFilter('status', '1')
  // Add Filter to Group.
  .addFilter('status', '2', '!=', 'publish_status')
  // Add Page Limit.
  .addPageLimit(5)
  // Add Fields.
  .addFields('node--article', ['field_a.id', 'field_b.uid', 'field_c.tid'])
  // Add Includes.
  .addInclude(['field_a.id', 'field_b.uid', 'field_c.tid'])
  // Add multiple sort criterion.
  .addSort('id', 'DESC')
  .addSort('uid')
  .addSort('status');

const urlencodedQueryString = apiParams.getQueryString();
const queryString = apiParams.getQueryString({ encode: false });

API

getQueryString [options?]

Returns query string which can be used in api calls. By default the output is URI encoded. Options can be passed to control the qs.stringifying internally used.

addFilter

Used to restrict items returned in a listing.

ParamsTypeDescription
pathstringA 'path' identifies a field on a resource
valuestringstring[]
operatorstring(Optional) An 'operator' is a method of comparison
groupstring(Optional) Name of the group, the filter belongs to

Following values can be used for the operator. If none is provided, it assumes "=" by default.

  '=', '<>',
  '>', '>=', '<', '<=',
  'STARTS_WITH', 'CONTAINS', 'ENDS_WITH',
  'IN', 'NOT IN',
  'BETWEEN', 'NOT BETWEEN',
  'IS NULL', 'IS NOT NULL'

NOTE: Make sure you match the value supplied based on the operators used as per the table below

Value TypeOperatorDescription
string=, <>, >, >=, <, <=, STARTS_WITH, CONTAINS, ENDS_WITH
string[]IN, NOT IN
string[] size 2BETWEEN, NOT BETWEENThe first item is used for min (start of the range), and the second item is used for max (end of the range).
nullIS NULL, IS NOT NULLMust use null

Read more about filter in Drupal.org Documentation

addGroup

Used to group Filters. Groups can be nested too.

ParamsTypeDescription
namestringName of the group
conjunctionstring(Optional) All groups have conjunctions and a conjunction is either AND or OR.
memberOfstring(Optional) Name of the group, this group belongs to

addInclude

Used to add referenced resources inside same request. Thereby preventing additional api calls.

ParamsTypeDescription
fieldsstring[]Array of field names

Read more about Includes in Drupal.org Documentation

addSort

Used to return the list of items in specific order.

ParamsTypeDescription
pathstringA 'path' identifies a field on a resource
directionstringSort direction ASC or DESC

Read more about Sort in Drupal.org Documentation

addPageLimit

Use to restrict max amount of items returned in the listing. Using this for pagination is tricky, and make sure you read the following document on Drupal.org to implement it correctly.

ParamsTypeDescription
limitnumberNumber of items to limit to

Read more about Pagination in Drupal.org Documentation

addFields

The name of this method might be miss leading. Use this to explicitely request for specific fields on an entity.

ParamsTypeDescription
typestringResource type
fieldsstring[]Array of field names in the given resource type

addCustomParam

Use to add custom parameter to the query.

ParamsTypeDescription
inputobjectThe parameter object

E.g. usage

apiParams
  // To add `foo=bar` to the query.
  .addCustomParam({foo: 'bar'})
  // To add `foo[bar]=baz` to the query.
  .addCustomParam({ foo: {bar: 'baz'}})
  // To add `bar[0]=a&bar[1]=b&bar[2]=c` to the query.
  .addCustomParam({ bar: ['a', 'b', 'c']})

Helper methods

clear

Clears all query parameter constructed so far.

getQueryObject

Get object representation of the query object generated so far.

initialize

Re-initialize with a query string/object or another instance of DrupalJsonApiParams

initializeWithQueryObject

Re-initialize with previously stored data from getQueryObject

initializeWithQueryString

Re-initialize with previously stored data from getQueryString

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100