Brian Perry Discusses Latest Updates and Future Vision for the API Client Initiative

The Drupal API Client introduces a simplified method for engaging with common Drupal APIs via a suite of JavaScript packages. While the JSON client remains widely utilized, the initiative extends further to encompass a base API Client package and a client tailored for Decoupled Routers. Anticipating future growth, there's potential for additional Drupal APIs to be supported. Previously, we explored this initiative with Brian Perry, an accomplished web developer and an integral part of the Drupal community. We recommend reading our earlier interview with Brian Perry here: Deep Dive into Drupal's API Client Initiative with Brian Perry (thedroptimes.com)

Additionally, the API Client initiative secured victory at the DrupalCon Pittsburg Pitch-burgh Innovation Contest, further highlighting its significance within the Drupal ecosystem. In this interview, we reconnect with Brian Perry to delve into the evolution of the API Client initiative and its current trajectory.

"Our primary motivation to submit to the Pitch-burgh competition was for community visibility, which I think was a huge success."

stated Brian

This interview conducted by Kazima Abbas, sub-editor at The Drop Times, with Brian Perry provided insights into the evolution and current status of the API Client initiative following its success at the DrupalCon Pittsburg Pitch-burgh Innovation Contest. The interview highlighted significant milestones achieved since then, including the release of the 1.0 version of the JSON Client, extensive documentation efforts, and the completion of commitments stemming from the contest funding. Brian elaborated on the project's architectural decisions, such as making the API client extensible and enabling organic evolution during implementation.

Additionally, he discussed the potential impact of the initiative on the broader Drupal community, particularly through initiatives like promoting the Drupal API Client packages to the Drupal namespace on npm. Looking ahead, Brian shared his vision for the future of the API Client beyond the 1.0 release, emphasizing opportunities for further innovation, collaboration, and improved developer experiences within the Drupal ecosystem.

Now, let's delve into this detailed interview and gain insights into the progress of the API Client initiative, as shared by Brian,

TDT[1]: Can you provide an overview of the latest updates shared regarding the API Client initiative at DrupalCon Portland?

Brian Perry: Our biggest update is that we've completed our Pitch-burgh commitment and released the 1.0 version of our JSON:API Client. We’ve also invested substantial time into our documentation which is published on GitLab Pages and includes live code examples.

TDT[2]: Reflecting on your success in winning the DrupalCon Pittsburg Pitch-burgh Innovation Contest a year ago, how has the API Client initiative evolved since then?

Brian Perry: One of our initial implementation decisions was to make the API client extensible, which I think made it possible for the project to evolve organically during implementation. Even though our main goal was to create a JSON:API client, we started by creating a base API client class and extending that class to create the JSON:API client. During implementation, anything that we believed could be useful for communicating with any type of Drupal API (authentication utilities for example) was added to the base class, and anything specific to JSON:API was added to the JsonApiClient class.

When it came time to add support for the Decoupled Router module to the JSON:API client, this architecture made it possible for us to create a standalone Decoupled Router Client package, and use that as a dependency of the JSON:API Client. We didn’t plan to publish a Decoupled Router package as part of this phase, but we were able to do so with a comparable amount of code, while also meeting the needs of the JSON:API Client.

Another thing that became clear as the project became a reality is that there is a large ongoing opportunity for this project to either support or document a wide variety of common decoupled use cases. Our documentation demonstrates a variety of examples for different JavaScript frameworks for example. We also recently published a utilities package. Currently, that package just has caching-related utilities, but it could be the home of other general-purpose utilities in the future. We’re considering adding utilities to make it easier to work with Drupal media entities for example.

TDT[3]: Congratulations on the release of the Drupal API Client 1.0! Please provide more details about this release's main features and functionalities, particularly highlighting its fully functional JSON:API capabilities.

Brian Perry: Our main 1.0 release was the @drupal-api-client/json-api-client package. This release fully supports the implementation of the JSON:API specification included in Drupal Core, both for read-only requests for collections and individual resources, and requests that modify resources. All JSON:API parameters are also supported, allowing requests to be filtered, sorted, and referenced data to be included in the response. The client supports working with localised content as well.

And slightly beyond what is offered in Drupal Core, the client has built-in support for basic authentication, authentication using Simple oAuth, and custom authorization headers. We also support getting individual resources by path for sites that have the Decoupled Router module enabled.

TDT[4]: Could you share more about the commitment completion resulting from the funding received from the Pitch-burgh innovation contest? How did this funding contribute to the development of the API Client?

Brian Perry: Our primary motivation to submit to the Pitch-burgh competition was for community visibility, which I think was a huge success. Receiving funding was helpful, but not without challenges. We decided to establish an Open Collective, which took time and also had an impact on how we could and couldn’t make use of the funds. But at the end of the day, we were able to pay some contributors as a result, and we also now have remaining funds in the open collective. I’m hoping this can allow us to sponsor development on future API Client-related work, and also pay for things like hosting, for example, API endpoints, and showcase instances.

TDT[5]: With the publication of detailed documentation on GitLab Pages, including live code examples, how do you envision this resource benefiting developers and users of the API Client?

Brian Perry: Since the API Client is a lower-level building block that can be used with a variety of JavaScript frameworks, having robust documentation is an important step to help developers understand how it could be used within their projects. Being able to see a concrete example of using the client with their JavaScript framework of choice can go a long way for example.

There have also been limited contributions to the Drupal.org Decoupled Drupal documentation. I’ve wondered for a while if part of the reason for this is that the problem space for Decoupled is too broad, making it difficult to have a cohesive starting point. If the API Client gains adoption I wonder if it might serve as a more understandable starting point for other Decoupled use cases.

TDT[6]: Regarding the proposal to promote the Drupal API Client packages to the Drupal namespace on npm, what motivated this decision, and what impact do you anticipate it will have on the broader Drupal community?

Brian Perry: Currently, Drupal’s presence on NPM is fragmented, with only a few narrowly focused packages offered under the Drupal namespace. I believe developers who plan on using Drupal as an API expect to see ‘official’ utilities on NPM. Offering packages like the Drupal API client under the Drupal namespace could help improve the perception of Drupal outside of the Drupal community and signal that we’re serious about JavaScript and headless use cases.

Doing this would also force several important process and governance discussions. What criteria must be met for a package to be offered under the Drupal namespace? Who has ownership of the project? How are security and security updates handled? What are the standards for releases and release cadence? Answering these questions would be useful for the Drupal project broadly.

TDT[7]: You mentioned refining the 1.x roadmap for the API Client. Can you discuss some of the proposed priorities, such as TypeScript improvements and automatic type generation, and how community feedback will shape these initiatives?

Brian Perry: Our packages thus far are written in TypeScript and can be used with TypeScript, but we believe that there are many opportunities to provide easier and improved type safety when working with custom Drupal content models. By taking advantage of a combination of solutions like JSON Schema and JavaScript libraries like Zod, we believe it would be possible to automatically determine the schema for your Drupal content and provide IDE autosuggest, and type validation at both compile time and run time.

We’ve also heard some community interest in moving forward with creating a GraphQL client, which we believe will be greatly simplified due to our existing base API Client class. We have other possible issues under our 1.x meta issue, but we’d greatly prefer to focus on things that users of our packages find valuable.

TDT[8]: How do you envision the future of the API Client evolving beyond the 1.0 release, and what opportunities do you see for further innovation and collaboration within the Drupal ecosystem?

Brian Perry: If the API Client is adopted by the community, I believe there will be a lot of opportunity for this project to grow. Common use cases can find their way into utilities and new packages that will hopefully continue to cut down the custom or boilerplate code needed to work with Drupal data in JavaScript front ends. Developers can extend our tools into new, opinionated packages, and new front-end starter kits can be created that use our client as a dependency.

Hopefully, this can all be in service of improving developer experience working with Drupal in Decoupled builds, spending less time on things like interfacing with Drupal’s JSON:API endpoints, and more time creating great front-end experiences powered by Drupal.