API-First Drupal: what's new in 8.6?

published on October 2, 2018

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 1 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:

    POST /node?_format=json HTTP/1.1
Content-Type: application/json

{
  "type": [{"value": "article"}],
  "title": [{"value": "Dramallama"}],
  // Note that this is using the file ID we got back in the response to our previous request!
  "field_hero_image": [
    {
      "target_id": 345345,
      "description": "The most fascinating image ever!"
    }
  ]
}

    If you’d like a more complete example, see the change record, which explains it in detail. And if you want to read about the design rationale, see the dedicated blog post.

  2. parent field on Term now is a standard entity reference #2543726

    "parent": [] ⬇ 

    "parent":[{
  "target_id": 2,
  "target_type": "taxonomy_term",
  "target_uuid": "371d9486-1be8-4893-ab20-52cf5ae38e60",
  "url": "https://example.com/taxonomy/term/2"
}]
    We fixed this at the root, which means it not only helps core’s REST API, but also the contributed JSON API and GraphQL modules, as well as removing the need for its previously custom Views support!

  3. alt property on image field lost in denormalization #2935738

    "field_image":[{
  "target_id": 2,
  "target_type": "file",
  "target_uuid": "be13c53e-7f95-4add-941a-fd3ef81de979",
  "alt": "Beautiful llama!"
}]

    after denormalizing, saving and then normalizing, this would result in:

    "field_image":[{
  "target_id": 2,
  "target_type": "file",
  "target_uuid": "be13c53e-7f95-4add-941a-fd3ef81de979",
  "alt": ""
}]

    Same thing for the description property on file and image fields, as well as text, width and height on image fields. Denormalization was simply not taking any properties into account that specializations of the entity_reference field type were adding!

  4. PATCHing a field → 403 response without with reason #2938035

    {"message":"Access denied on updating field 'sticky'."} ⬇ {"message":"Access denied on updating field 'sticky'. The 'administer nodes' permission is required."}

    Just like we improved PATCH support in Drupal 8.5 (see point 4 in the 8.5 blog post), we again improved it! Previously when you’d try to modify a field you’re not allowed to modify, you’d just get a 403 response … but that wouldn’t tell you why you weren’t allowed to do so. This of course was rather frustrating, and required a certain level of Drupal knowledge to solve. Now Drupal is far more helpful!

  5. 406 responses now lists & links supported formats #2955383

    Imagine you’re doing a HTTP request like GET /entity/block/bartik_branding?_format=hal_json. The response is now more helpful.

    
Content-Type: application/hal+json

{"message": "No route found for the specified format hal_json."}

    ⬇

    
Content-Type: application/hal+json
Link: <http://example.com/entity/block/bartik_branding?_format=json>; rel="alternate"; type="application/json", >http://example.com/entity/block/bartik_branding?_format=xml>; rel="alternate"; type="text/xml"

{"message": "No route found for the specified format hal_json. Supported formats: json, xml."}

  6. Modules providing entity types now responsible for REST tests

    Just like we achieved comprehensive test coverage in Drupal 8.5 (see point 7 in the 8.5 blog post), we again improved it! Previously, the rest.module component in Drupal core provided test coverage for all core entity types. But if Drupal wants to be API-First, then we need every component to make HTTP API support a priority.
    That is why in Drupal 8.6, the module providing an entity type contains said test coverage (A). We also still have test coverage test coverage (B). Put A and B together, and we’ve effectively made HTTP API support a new gate for entity types being added to Drupal core. Also see the dedicated blog post.

  7. rest.module is now maintainable!

    I’m happy to be able to proudly declare that Drupal 8 core’s rest.module in Drupal 8.6 can for the first time be considered to be in a “maintainable” state, or put differently: in a well-maintained state. I already wrote about this in a dedicated blog post 4.5 months ago. Back then, for the first time, the number of open issues fit on “a single page” (fewer than 50). Today, several months later, this is still the case. Which means that my assessment has proven true :) Whew!

Want more nuance and detail? See the REST: top priorities for Drupal 8.6.x issue on drupal.org.

Are you curious what we’re working on for Drupal 8.7? Want to follow along? Click the follow button at REST: top priorities for Drupal 8.7.x — whenever things on the list are completed (or when the list gets longer), a comment gets posted. It’s the best way to follow along closely!2

The other thing that we’re working on for 8.7 besides the REST API is getting the JSON API module polished to core-worthiness. All of the above improvements help JSON API either directly or indirectly! I also wrote about this in my State of JSON API blog post. Given that the REST API is now in a solid place, for most of 2018 the majority of our attention has actually gone to JSON API, not core’s REST API. I expect this to continue to be the case.

Was this helpful? Let me know in the comments!

For reference, historical data:

  1. This blog post is long overdue since 8.6 was released almost a month ago. Some personal life issues caused a delay. ↩︎

  2. ~50 comments per six months — so very little noise. ↩︎

Comments

plach's picture
plach

Thanks Wim! The quality (and quantity) of your work is simply incredible :)

plach's picture
plach

I’m sure that a lot of people were involved in such great accomplishments, but what’s amazing is how you’re always able to manage and shape things so that they happen smoothly and exactly the way they should be :)

Wim Leers's picture
Wim Leers

Oh … hah :D It’s not at all smooth. But I’m glad that it looks like that to you. If I’m making it look simple, that probably means I’m succeeding in communicating things clearly :)