Skip to main content
Technical Writer, DocOps Engineer
Sep 01, 2022

By: Ádám Balogh and co-author Ákos Seress (technical advisor, Front-end developer)

Tradition and progress: just as in the case of architecture, but in the world of developer portals as well, it is important not to consider only the technological advantages when making a decision. The design, the service, and the content must form one organic unit and serve everyone who is part of the developer portal’s ecosystem, be it a developer, a designer, a content editor, or an API consumer.

This study reviews the articles already published by the Pronovix team on the subject, takes them as a basis, but also looks further. Its purpose is to present the trends that have become popular in the world of Content Management Systems (CMS) and to contextualize these with the needs of developers, administrators, and users. To do this, we first need to familiarize ourselves with some basic concepts, then we have to compare the advantages and disadvantages of the different architectures. We recommend the first two parts of this article to any reader interested in the topic. The third part is mainly for Drupal developers, and contains tips & tricks and best practices that may help them using JSON:API.

Overview of the journey you’re about to take

Part 1: Developer portal – technology and community

The introduction section of this article is conceptual, so it’s also optimal for readers who aren’t familiar with Content Management Systems (CMS) and developer portals:

Part 2: Tradition or progress – why not both?

You will find definitions, pros & cons of the different architectures, as well as the reasons why we vote for the progressively decoupled Drupal approach in terms of devportals:

Part 3: Progressively Decoupled Drupal with JSON:API – lessons learned

We provide experienced Drupal developers with best practices, workarounds, and case studies we collected during our journey. This section contains technical details regarding how to solve problems in Drupal with JSON:API:

Part 1: Developer portal – technology and community

When and why to use a CMS

As the maturity level [1] of your company increases with the complexity [2] of your products and the number of contributors in your development team, you might want to consider switching from a lightweight solution (for example from a Static Site Generator) to a CMS. A CMS can reliably scale to your needs.[3]

Building a developer portal at a certain point in the process is essential, because:

  • frictionless collaboration and cooperation between developers are fundamental for successful product development,
  • attracting others to use your products requires a self-service hub where external developers and different stakeholders can learn about and try out your services before a real commitment.

What is a developer portal

A developer portal - often shortened to devportal - is an interface between digital and human agents (for example, a set of APIs, SDKs, or other interactive digital tools and their various stakeholders). The portal can play several roles to achieve the business goals of an organization.[4]

Why Drupal is optimal for building developer portals

In one of our previous blog posts [5], we collected a list of arguments for why Drupal is an optimal CMS for building developer portals. For example, Drupal:

  • does not require a developer for every little change,
  • is supported by a community of dedicated contributors,
  • makes life easy for content creators with its built-in text editor and drag-and-drop-like page-building features,
  • has extensive support for standard accessibility technologies,
  • is mobile-first out of the box,
  • supports multilingual content management,
  • is a well-protected and secure system.

A Drupal developer portal can grow with your needs, so your team can start developing solutions that serve your audience the best.

Contributors and their requirements

We collected a list of all parties who contribute to the process and the solutions they require to make their job and your project successful:

Contributors Who are they What they require Out-of-the-box (OOTB) solutions in Drupal
Developers Those people who develop your products and build the site for you. - Front-end developers: a framework that helps to develop creative solutions that follow the most current trends and user expectations.
- Back-end developers: sophisticated and secure back-end.
- Paragraphs,
- Layout builder,
- Views,
- Twig extensions,
- CKEditor templates,
- sophisticated role-based permission matrix,
- excellent content modeling features,
- JSON:API, etc.
Content Editors/Site admins They populate the developer portal with engaging content besides the highly technical reference documentation. - No-code or low-code solutions to build visually appealing and complex pages,
- a toolkit that they are familiar with to produce and maintain content.
- WYSIWYG editor,
- reusable, customizable yet standardized content templates (content types),
- drag-and-drop-like page-building features.
Visitors The users who consume and benefit from the products and the content. Nice and interactive portal. N/A.

Drupal out-of-the-box addresses the needs of the back-end developers and supports a wide variety of tools that can make the editors’ life easier, too. But what about front-enders and visitors?

Let’s consider the websites of Netflix or Facebook. Users expect that a modern site always stays interactive and users will always remain on the same page even if the content needs some time to load.

One of the most popular solutions for this is the so-called CSS Skeleton Loading Animation, where placeholders appear only on the page representing the content that is being collected or generated in the background.

developer's journey

These are usually embedded into JavaScript (JS) frameworks. But JS can result in slower performance.

Sometimes, classic (or we can even say traditional) Drupal solutions (PHP, JS, twig) by themselves aren’t enough to address all developer and user needs. Sometimes, experienced Drupal front-end developers, for example, want to try out new technologies and integrate them with Drupal, so they wouldn’t depend on the changes in the CMS system.

Part 2: Tradition or progress – why not both?

In the following sections, the listed architectures are considered in the devportals’ context, taking into account the needs of the contributors summarized in the chart above.

Our comparison chart gives a better overview.

Traditional Drupal CMS

Traditionally, Drupal CMS is a monolithic system, which means that server-side and client-side processes take place within a common, organically connected system. The data is stored in the Drupal database, and then the data is interpreted by and represented in the browser through the so-called PHP rendering. This close integration allows Drupal to remain customizable and secure, and also provides useful features like:

  • live preview,
  • taxonomy management that enables content categorization,
  • access control,
  • administrative tools for content creation and user management,
  • no-code page building.

We don’t necessarily have to deviate from the traditional path, for example, if we are targeting those users for whom “modern” and “popular” visual solutions aren’t important as long as:

  • the site is reliable and transparent,
  • the content is always available and regularly updated,
  • it is easy to access the APIs and other digital assets available on the portal, and
  • the users get all the help they need to implement them.

In short, as long as the content and features are satisfactory.

Beyond traditional

If the traditional methods and solutions no longer satisfy our needs, we can do three things.

1. Switching to another solution

The first one is that we look for a completely new solution, and replace the entire system. It might seem to be the easiest way, but in the short and in long run, it requires the most resources and causes many problems. The transition is complicated because all contributors have to accommodate the new environment. Let’s recall the requirements in the chart from Part 1: we can see that none of the contributors necessarily have an interest in completely breaking with the well-known methods.

developer's journey

Replacing our system completely is a good idea in case the system isn’t flexible enough to be able to adapt to our needs. Drupal is fortunately not like that.

2. Fully decoupled, fully headless

If our development team is dedicated enough and we have a lot of resources, we can eliminate Drupal’s default front-end entirely: we can decouple it from the back-end. In this case, we have to develop our own front-end layer (using, for example, React, Angular, Gatsby, or Vue), while Drupal will only function as a database that manages and stores data and communicates with the front-end via a web API (for example, JSON:API or GraphQL).

This fully decoupled or headless method can be considered an option if we don’t want to keep any of Drupal’s administrative services, and we agree to sacrifice all OOTB functions related to content management on the altar of full customization because the self-developed framework is worth the sacrifice.

developer's journey

In this case, the back-end developers can keep Drupal’s sophisticated back-end, and the front-end developers can try out and use the most modern frameworks, thereby guaranteeing the most spectacular web experience for the users. At the same time, we have to provide administrators and editors who are responsible for content management with an easy-to-learn, familiar editorial interface so that they can continue to perform their tasks without friction. We also have to cope with new challenges such as we have to replace the now lacking taxonomies that Drupal provides OOTB, or the lack of access control, etc.

3. Decoupled VS Traditional

There are some who fully advocate “headlessness” and even see it as the future of Drupal, while others reject the whole concept, saying it won’t solve any of our problems. In fact, neither of them is necessarily right. The chosen technology alone isn’t a guarantee of success. Different approaches provide help in tackling different kinds of challenges. The most important thing is still the quality of the service and communication: the content and support that the dedicated teams provide to the audience. This is what primarily determines the success of the enterprise.

developer's journey

Progressively decoupled Drupal

The third path that lies in between the traditional monolithic and the fully-decoupled approaches is called progressive decoupling.

In the cases of developer portals, security and reliability are primary considerations, and we must also provide a transparent administration interface:

  • which enables Site administrators to easily moderate the site’s users and pages,
  • which enables Content editors to easily modify the content on the site,
  • which ensures search engine optimization (SEO) possibilities, and
  • complex content organization, and
  • access control.

If we fully “decouple” such a system, we have to say goodbye to all of these.

What can we do if we want to integrate single-page applications working with dynamically changing data into our developer portal?

The answer: use dynamic content only where necessary.

In a Progressively decoupled Drupal-based portal, the server-side and browser-side functions are still organically connected to each other, just like in the case of the traditional approach. It is also possible to embed modern JS-based (for example, React, Angular, Vue) components in the pages. Drupal provides the components with the data required for their operation from its own database via a web API (for example, JSON:API or GraphQL).

drupal, traditional, fully decoupled, progressively decoupled

As a result:

  • well-proven tools, environments, and interfaces are still provided for back-end developers and content editors;
  • front-end developers can take advantage of most modern JS technologies.

All contributors can increase further the user experience by seamlessly working together.

Comparison chart

Approach Description Pros Cons
Traditional Drupal A monolithic system. Server-side and client-side processes take place within a common, organically connected system. Customizable, secure, and reliable. It also provides such useful functions like:

- transparent administration interface for content creation and user management,
- live preview,
- taxonomy management that enables content categorization,
- access control,
- no-code page building,
- built-in multi-lingual support,
- built-in accessibility support.
- Rigid. Monolithic.
- Sometimes, traditional Drupal solutions (PHP, JS, twig) by themselves aren’t enough to address all developer and user needs.
Fully-decoupled (headless) Drupal Drupal functions as a database that communicates with a custom-developed and maintained front-end solution via a web API. - Future-proof design.
- Provides full control over how the displayed content appears.
- Developers can use their favorite frameworks.
- Supports multi-platform solutions.
- Drupal’s built-in front-end functions and administrative services are completely lost.

- The development team is responsible for and must take care of security, accessibility, and more
Progressively decoupled Drupal Server-side and client-side functions are organically connected, but modern JS-based components are embedded in the pages. Drupal provides the data via a web API (JSON:API or GraphQL). - Well-proven tools, environments, and interfaces provided OOTB by Drupal are still there for back-end developers and content editors.
- Front-end developers can take advantage of the most modern JS technologies.
With new technology, comes new challenges.

Part 3: Progressively Decoupled Drupal with JSON:API - lessons learned

This section is recommended for experienced Drupal developers.

developer's journey
Photo by Tyler B on Unsplash

What is JSON:API module?

JSON:API has a module implementation that made itself into Drupal core in 2019, and it’s been supported and developed by the Drupal community since then.

JSON:API can be used as an interface (a bridge) between the Drupal database and a custom front-end JS framework: you can reach every Drupal entity via the endpoints of the JSON:API using standard HTTP methods. What Drupal entities are? For example, blog posts, users, comments, page titles, taxonomy terms, authors, uploaded images, translations, and revisions (previous states of the pages). You can retrieve, filter, and sort almost every data that gets into the Drupal database.

Problems with JSON:API

Predictable routes

One of the most known and severe “issues” with JSON:API lies in its most powerful feature. If every data can be retrieved through an HTTP request, it’s possible for bots and developers to request and fetch sensitive information. They could find the usernames, which, if the users use their real email addresses as their username, is a privacy breach and also violates the GDPR regulation.

Solutions to this problem

Don’t allow JSON:API to reach user information, so they won’t appear in the response.
Hide the user information from the response of the /user/user endpoint as exposing it is against GDPR.
Install and enable the JSON:API Extras module. That module lets you customize the default behavior of JSON:API, so you can restrict the retrievable fields (security by obscurity).

Read more

Undocumented scenarios

The JSON:API module is well-documented, but in certain edge cases, it’s hard to find sufficient guidance on the official site. For example, if you’d like to filter multiple fields, and you want AND relations between the items, it’s not clear how you can do it. We provide you with a possible answer that you can find in the Filtering with logic section.

Multiple API calls needed to retrieve multiple values

Some useful resources can’t be fetched easily, like the names of the taxonomy terms, or the image location URLs. In the response, only their IDs are present.

In these cases, you can use the Include request parameter, which returns an array that contains all requested information.

If you’d like to fetch multiple resources, you have to send multiple requests, then your JS framework or a custom backend solution has to process the retrieved data bundles.

developer's journey

Case studies

1. Simple filtering by taxonomy terms without any logic

It is possible to filter the content by their taxonomy terms, then display the filtered content right after a user clicked on a link, without reloading the page.

The implementation is well-documented on

Real-life example:

2. Collecting URLs using Includes

In case you want to display images on the pages, you might want to know how you can collect their URLs, or how you can collect the names of some taxonomy terms. As we stated in the “Problems” section before, by default, you can’t retrieve the location URLs of the images and the names of the taxonomy terms through the JSON:API.

A possible solution is to use Includes.
You have to do multiple API calls because you have to request the resources one by one.

For example:


2.1. Problems with Includes

JSON:API collects the requested and the related data into one data structure but the relationship between them won’t be “visible”. Like if you’d put all LEGO blocks into a big bag. The JS has to resolve this issue by pairing the resources with their matching IDs.

The bright side:

For example, if you’d like to retrieve all taxonomy terms used on different pages throughout the portal, JSON:API will check the nodes first, then it’ll look for the related terms. So those taxonomy terms won’t be returned that don’t have a related node or the users aren’t permitted to see.

3. Filtering with logic

How to develop a feature that filters the content by terms, then categorizes them?

JSON:API, by default, uses AND relationships, but what if you want to use multiple fields?

If you’d like to request the cat AND the dog fields one by one: it works just fine.
But what if you have a field called “animals” that contains values like cats, dogs, horses, and birds, and you’d like to collect only the cats and dogs?

You need to use Condition Groups. The URLs can be extremely long.

And what if you want to search in the already categorized and filtered results? The URL won’t be pretty, but will work:[title][operator]=CONTAINS&filter[title][value]=visa&filter[field_ongoing][value]=1&filter[status][value]=1&include=field_site_image&fields[file--file]=uri&page[offset]=0&page[limit]=15

Kudos to Gabe Sullice

4. Weight-based ordering

How can you develop an FAQ with REACT, and order the items by their weight? You have to reorder the arrays according to the weights of the objects.

JSON:API can do this as well. For example, you can list the content in chronological order (JSON:API sorting is well documented).

Example URL:[langcode]=en&include=field_faq_tags&sort=field_faq_weight

5. Show parent-child relationships in nested filters

You can gather this kind of information using the JSON:API.

In the response, you can find the IDs of the parent items of the components, so you have to do the same workaround we described in the 2nd use case to retrieve their names.

6. Translation-localization

Let’s suppose that you can select different languages from a list on a page (ENG and BG). By default, after you’ve selected an item (e.g., BG), a new node is generated with the selected lang="bg" code. It’s possible to create one node with content in different languages without generating a new node.

The full URL contains the non-default lang codes, but the lang code isn’t part of the base URL. The lang code appears in the JSON:API object, you can request the data from there.


Other sources:

All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.

Ádám is a Technical Writer at Pronovix. Before joining Pronovix, he was working in the field of digital philology. Now, as a technical writer, he dedicated himself to developing tools and methods to make documentation writing and testing more efficient and automatic.


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.