API

Drupal 8’s REST API reached a next level of maturity in 8.5. In 8.6, we matured it further, added features and closed some gaps.

Drupal 8.6 was released ¹ with some significant API-First improvements!

The REST API made a big step forward with the 6th minor release of Drupal 8 — I hope you’ll like these improvements :)

Thanks to everyone who contributed!

1. File uploads! #1927648

   No more crazy per-site custom REST resource plugins, complex work-arounds or base64-encoded hacks! Safe file uploads of any size are now natively supported!

   POST /file/upload/node/article/field_hero_image?_format=json HTTP/1.1
   Content-Type: application/octet-stream
   Content-Disposition: file; filename="filename.jpg"
   [… binary file data …]

   then, after receiving a response to the above request:

Quite a few people in the Drupal community are looking forward to see the JSON API module ship with Drupal 8 core.

Because:

• they want to use it on their projects
• the Admin UI & JS Modernization Initiative needs it
• they want to see Drupal 8 ship with a more capable RESTful HTTP API
• then Drupal will have a non-NIH (Not Invented Here) API but one that follows a widely used spec
• it enables them to build progressively decoupled components
• …

So where are things at?

Timeline

Let’s start with a high-level timeline:

Two big “maintainability” milestones have been hit in the past few days:

1. rest.module now is in a maintainable state

For the first time ever, the issue tracker for the rest.module Drupal core component fits on a single page: https://www.drupal.org/project/issues/drupal?component=rest.module. 48 46 open issues, of which several are close to RTBC, so that number will likely still go down. Breakdown:

• 19 of those 48 are feature requests.
• 6 are “plan” issues.
• At least 10 issues are related to “REST views” — for which we are only fixing critical bugs.
• And 12 are postponed — blocked on other subsystems usually.

(There is overlap among those breakdown bullets.)

Finally the REST module is getting to a place where it is maintainable and we’re not extinguishing whatever the current fire is! It’s been a long road, but we’re getting there!

This blog post summarizes the 572 comments spanning 5 years and 2 months to get REST file upload support in #1927648 committed. Many thanks to everyone who contributed!

From February 2013 until the end of March 2017, issue #1927648 mostly … lingered. On April 3 of 2017, damiankloip posted an initial patch for an approach he’d been working on for a while, thanks to Acquia (my employer) sponsoring his time. Exactly one year later his work is committed to Drupal core. Shaped by the input of dozens of people! Just look at that commit message!

Background: API-First Drupal: file uploads!.

Drupal 8’s REST API has been maturing steadily since the Drupal 8.0.0 was released in November 2015. One of the big missing features has been file upload support. As of April 3 2018, Drupal 8.6 will support it, when it ships in September 2018! See the change record for the practical consequences: https://www.drupal.org/node/2941420.

It doesn’t make sense for me to repeat what is already written in that change record: that already has both a tl;dr and a practical example.

What I’m going to do instead, is give you a high-level overview of what it took to get to this point: why it took so long, which considerations went into it, why this particular approach was chosen. You could read the entire issue (#1927648), but … it’s one of the longest issues in Drupal history, at 572 comments¹. You would probably need at least an entire workday to read it all! It’s also one of the longest commit messages ever, thanks to the many, many people who shaped it over the years:

Now that Drupal 8’s REST API ¹ has reached the next level of maturity, I think a concise blog post summarizing the most important API-First Initiative improvements for every minor release is going to help a lot of developers. Drupal 8.5.0 will be released next week and the RC was tagged last week. So, let’s get right to it!

The REST API made a big step forward with the 5th minor release of Drupal 8 — I hope you’ll like these improvements :)

Thanks to everyone who contributed!

1. text fields’ computed processed property exposed #2626924

   No more need to re-implement this in consumers nor work-arounds.

This blog has been quiet for the last year and a half, because I don’t like to announce things until I feel comfortable recommending them. Until today!

Since July 2016, API-First Drupal became my primary focus, because Dries felt this was one of the most important areas for Drupal’s future. Together with the community, I triaged the issue queue, and helped determine the most important bugs to fix and improvements to add. That’s how we ended up with REST: top priorities for Drupal … plan issues for each Drupal 8 minor: