State of JSON:API (November 2018)

published on November 21, 2018

Gabe, Mateu and I just released the second RC of JSON:API 2, so time for an update! The last update is from a month ago.

What happened since then? In a nutshell:

  • Usage has gone up a lot! 2.0-RC1: 0 → 250, 2.x: ~200 → ~330 1
  • 2.0-RC2 released :)
  • RC1 had about half a dozen issues reported. Most are fixed in RC2. 2
  • The file uploads feature: 80% → 100%, will ship in 2.1!
  • The revisions feature 3: 80% → 90%, will ship in 2.2!
  • New core patch to bring JSON:API to Drupal core: #2843147-78

RC2

Curious about RC2? RC1 → RC2 has four changes:

  1. Renamed from JSON API to JSON:API, matching recent spec changes.
  2. One critical bug was reported by brand new Drupalist Peter van Dijk (welcome, and thanks for noticing something we had gotten used to!): the ?filter syntax was very confusing and effectively required the knowledge (and use) of Drupal internals. Now you no longer need to do /jsonapi/node/article?filter[uid.uuid]=c42…e37 to get all articles by a given author, but just /jsonapi/node/article?filter[uid.id]=c42…e37. This matches the JSON:API document structure: the abstraction is no longer leaky! The updated ?filter syntax is still 95% the same. 4
  3. JSON:API responses were no longer being cached by Page Cache. This was of course a major performance regression. Fortunately long-time Drupalist yobottehg discovered this!
  4. Massive performance increase for requests using sparse fieldsets such as ?fields[node--article]=title. Thanks to long-time Drupalist jibran doing quite a bit of profiling on JSON:API, something which Mateu, Gabe and I haven’t gotten around to yet. Moving 2 lines of code made his particular use case 90% faster! We’re sure there’s more low-hanging fruit, but this one was so tasty and so low-risk that we decided to commit it despite being in RC.

So … now is the time to update to 2.0-RC2!

The JSON:API team: 150/150/150

In the previous update, I included a retrospective, including a section about how it’s been to go from one maintainer to three. A month ago this happened:

11:08:15 <e0ipso> https://usercontent.irccloud-cdn.com/file/REdyLpD6/2018-10-24%2011-07-42.png
11:08:27 <e0ipso> Let's get that to 150, 150 and 150
11:08:31 <WimLeers> :D
11:08:46 <WimLeers> that'd be pretty cool indeed
11:09:05 <e0ipso> COMEON gabesullice you're slacking!
11:09:08 <e0ipso> hehe

That image was: The screenshot Mateu shared a month ago. Showing Wim at 149 commits, Gabe at 147, Mateu at 150.

Well, as of yesterday evening, it looks like this: JSON:API committer statistics showing that the three main maintainers each have 150 commits!

On top of that, mere hours after previous update went live, Gabe became an official API-First Initiative coordinator, together with Mateu and I:

Congrats Gabe, and thanks! :)

  1. Note that usage statistics on drupal.org are an underestimation! Any site can opt out from reporting back, and composer-based installs don’t report back by default. ↩︎

  2. Since we’re in the RC phase, we’re limiting ourselves to only critical issues. ↩︎

  3. Just GET, just for Node entities. Those 2 limitations are essential because core doesn’t have a formal API for revision access control. :| Yet! ↩︎

  4. This was not a regression in 2.x; this also affects JSON:API 1.x! It’s just more apparent in 2.x that this is a problem because we did make 2.x comply with the spec completely (which also was the reason for the 2.x branch: we needed to break backward compatibility to comply). We chose to embrace the feedback and introduce this additional BC break in the 2.x branch. Some of your requests will now return 400 responses, but they all include helpful error messages, providing concrete suggestions on how to change it. ↩︎