desarol / drupal-jsonapi-client Goto Github PK

License: MIT License

JavaScript 100.00%

drupal-jsonapi-client's Introduction

Drupal JSON:API Client

This package makes manipulating Drupal entities and resources easier via the JSON:API module which is now in Drupal core (8.7.x).

Installation

npm i --save drupal-jsonapi-client

yarn add drupal-jsonapi-client

Usage

ES6 module

import { GlobalClient, Entity ... } from 'drupal-jsonapi-client'

UMD

<script src="https://unpkg.com/[email protected]/lib/Browser.min.js"></script>
<script>
  const Entity = window.DrupalJsonApi.Entity
  
  Entity
  .Load('node', 'article', 'uuid')
  .then(entity => {
    console.log(entity)
  })
</script>

Key features

Lightweight - HTTP library agnostic, defaults to axios (3kb)
Cross platform - works in node.js and the browser
Drupal specific - abstracts away the nuances of working with Drupal's JSON:API implementation
Object oriented - leverages ES6 classes to neatly package JSON:API objects
Familiar - takes inspiration from Drupal's Entity API syntax

It's still in an early stage and contributions are welcome. The general idea is to maintain a base Entity class which can be extended to provide more context specific uses ie. Article extends Entity.

Here's some syntax sugar to sink your teeth into that illustrates the vision:

import { GlobalClient, Entity } from 'drupal-jsonapi-client'

GlobalClient.baseUrl = 'https://www.example.com'
GlobalClient.sendCookies = true // use this when running code on the same origin as Drupal

const doRequest = async () => {
  // Update an existing entity
  const entity = await Entity.Load('node', 'article', 'uuid')
  entity.title = 'Drupal JSON:API rocks!'
  // PATCH the existing entity
  await entity.save()

  // Create a new entity
  const newEntity = new Entity('node', 'article')
  // .setAttribute must be used here as Entity
  // doesn't know whether title should be
  // an attribute or a relationship
  newEntity.setAttribute('title', 'A brand new article!')
  // Future references to "title" can use .title
  newEntity.title = 'We changed the title'
  // POST the new entity
  await newEntity.save()
}
doRequest()

Examples

For more detailed usage, see the examples.

Environment support

Node.js

node.js >= 6.0.0

Browsers

The library works in all modern browsers.

https://netmarketshare.com

We bundle regenerator-runtime and proxy-polyfill so that the library works out of the box in IE11.

drupal-jsonapi-client's People

Contributors

Stargazers

Watchers

Forkers

ikphilip mglaman frega timothyjoh ckng laurencefass sujanshresthanet

drupal-jsonapi-client's Issues

Provide a default identifier for filters

It seems like identifiers can simply be numbers:

filter[0][condition][field]=uuid&filter[0][condition][value]=1234.

https://git.drupalcode.org/project/drupal/blob/8.8.x/core/modules/jsonapi/src/Query/Filter.php#L215-231

We shouldn't force users to provide an identifier when we can generate one for them.

Support for sorting?

Does this library support sorting of results?

I didn't see anything in the examples or readme.

Documentation/examples for error handling.

Thanks for supplying some examples to get started. Please can you provide a typical template for error handling if Drupal fails to deliver or passes back an error message.

Are there any base assumptions we can make/document about error handling?

Consider replacing axios for devour to abstract away JSON:API logic

It would be much less work on our end if we didn't have to maintain a JSON:API client at all and just focused on the Drupal specific configuration we are looking for.

Unfortunately devour requires some advanced configuration before you can start sending entities which would mean users would need to do some kind of prefetch of their entity configuration just to be able to use the library.

Create a product roadmap

Few things so far:

New API to follow JSON:API semantics religiously
Provide a way to pull entity definitions locally (default values, etc) and cache them for continued usage across page refreshes
Integrate devour-client to reduce / remove heavy lifting of serialization, etc

Create an easy way to fetch Entity configuration

We want to be able to provide an export like:

import { EntityStorage, GlobalClient } from 'drupal-jsonapi-client'

GlobalClient.baseUrl = 'https://example.com' // point the cannon
GlobalClient.authorization = `Basic ${btoa('username:password')}` // if required

await EntityStorage.fetch()
const Article = EntityStorage.NodeArticle
const article = new Article()
article.title = 'asdf'
article.body.value = '1234'
article.body.format = 'basic_html'
await article.save() // create a new NodeArticle

when doset this lib support Drupal9?

Hi ，you really did a great job ,this package make our work easier than before,but I wonder when will this lib support Drupal9?

do you support cross site requests & fetch configuration?

Do you support cross-site requests? The example code in the readme looks like its assuming same-origin.

  const Entity = window.DrupalJsonApi.Entity
  
  Entity
  .Load('node', 'article', 'uuid')
  .then(entity => {
    console.log(entity)
  })

This looks like quite a high level API (which is great!) but can I configure it and specify the URL and set up the necessary headers to make this work?

Thanks

When receiving an error from JSON:API throw it rather than just returning null

This will make the library much more predictable and testable and will hopefully provide users with less cryptic error messages.

Provide an API to bundle dependent requests into subrequests

Related: Auspicus/devour-drupal#1, #3

The subrequests module allows us to bundle multiple requests into a single request. This has the benefit of reducing network latency by reducing number of requests that need to be sent.