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:

• 8.2.x — results (25% of release notes issues)
• 8.3.x — results (10% of release notes issues)
• 8.4.x — results (14% of release notes issues)
• 8.5.x — in progress!

If you want to see what’s going on, start following that last issue. Whenever there’s news, I post a new comment there.

But enough background. This blog post is not an update on the entire API-First Initiative, it’s about a particular milestone.

100% integration test coverage!

The biggest problem we encountered while working on rest.module, serialization.module and hal.module was unknown BC breaks 1. Because in case of a REST API, the HTTP response is the API. What is a bug fix for person X is a BC break for person Y. The existing test coverage was rather thin, and was often only testing “the happy path”: the simplest possible case. That’s why we would often accidentally introduce BC breaks.

Hence the clear need for really thorough functional (integration) test coverage2, which was completed almost exactly a year ago. We added EntityResourceTestBase, which tests dozens of scenarios3 in a generic way4, and used that to test the 9 entity types, that already had some REST test coverage, more thoroughly than before.

But we had to bring this to all entity types in Drupal core … and covering all 41 entity types in Drupal core was completed exactly a week ago!

The test coverage revealed bugs for almost every entity type. (Most of them are fixed by now.)

Tip: Subclass that base test class for your custom entity types, and easily get full REST test coverage — 41 examples available!

Guaranteed to remain at 100%

We added EntityResourceRestTestCoverageTest, which verifies that we have test coverage for all permutations of:

• entity type
• format: json + xml + hal_json
• authentication: cookie + basic_auth + anon

It is now impossible to add new entity types without also adding solid REST test coverage!

If you forget that test coverage, you’ll find an ASCII-art llama talking to you:

Good people of #Drupal, I present unto you the greatest method of all time. https://github.com/drupal/drupal/blob/8.5.x/core/modules/rest/tests/src/Functional/EntityResource/EntityResourceRestTestCoverageTest.php#L141 pic.twitter.com/TiWLPt7duH

— webcsillag (@webchick) December 8, 2017

That is why we can finally say that Drupal is really API-First!

This of course doesn’t help only core’s REST module, it also helps the contributed JSON API and GraphQL modules: they’ll encounter far fewer bugs!

Thanks

So many people have helped! In random order: rogierbom, alexpott, harings_rob, himanshu-dixit, webflo, tedbow, xjm, yoroy, timmillwood, gaurav.kapoor, Gábor Hojtsy, brentschuddinck, Sam152, seanB, Berdir, larowlan, Yogesh Pawar, jibran, catch, sumanthkumarc, amateescu, andypost, dawehner, naveenvalecha, tstoeckler — thank you all!5

Special thanks to three people I omitted above, because they’re not well known in the Drupal community, and totally deserve the spotlight here, for their impressive contribution to making this happen:

• arshadcn from the U.S. — helped on loads of the test coverage issues, often posting so many patches I had trouble keeping up!
• vaplas from Belarus — helped on almost every test coverage issue, and posted an epic comment on the three most important submilestones, making everyone smile: one, two, three
• jamesdesq from the U.K. — helped on many of of the test coverage issues, and wrote an amazing blog post titled How I learned to stop worrying and love Drupal contribution about his experience. One of those issues was his very first core patch!

That’s thirty contributors without whom this would not have happened!

And of course thanks to my employer, Acquia, for allowing me to work on this full-time!

Next

What is going to be the next big milestone we hit? That’s impossible to say, because it depends on the chains of blocking issues that we encounter. It could be support for modifying and creating config entities, it could be support for translations, it could be that all major serialization gaps are fixed, it could be file uploads, or it could be ensuring all normalizers work in both rest.module & jsonapi.module …

The future will tell, follow along!

1. Backwards Compatibility. ↩︎

2. Nowhere near 100% test coverage, definitely not every possible edge case is tested, and that is fine. ↩︎

3. Including helpful error responses when unauthenticated, unauthorized or just a bad request. This vastly improves DX: no need to be a Drupal expert to talk to a REST API powered by Drupal! ↩︎

4. It is designed to be subclassed for an entity type, and then there are subclasses of that for every format + authentication combination. ↩︎

5. And this is just from all the per-entity type test issues, I didn’t look at the blockers and blockers of blockers. ↩︎

• Acquia
• Drupal
• API