Building stable software in shifting space with APIs, extensions and webhooks
Did you know that construction of the International Space Station is never finished? Though it was first launched in 1998 and crewed since 2000, the ISS is still being assembled over 20 years later. This isn’t an oversight. The ISS is designed to be modular so that all components are maintainable, replaceable and extensible. The designers and engineers planned for uncertainty: There was no way to be sure what exact modules the ISS would need in the future.
What we’re working on isn’t rocket science, but there’s one big similarity. We’re designing a platform for an uncertain future. Especially with the increasing rate of new technology and end devices, we can’t know exactly which components and tools our customers will need tomorrow — they might not even exist yet.
APIs make change less painful
Our best bet, from an engineering perspective, is to make it as easy as possible to dock on to our core platform while ensuring the stability of the system on which it’s built — in this case our APIs. We make a commitment to our users that they can rely on our APIs’ consistency and integrate our platform with their systems without any breaking changes.
We’ve been developing our core APIs, Content Management and Content Delivery, for more than six years, adding countless features while maintaining stable versions. No API is perfect—and ours aren’t either—but we hold ourselves accountable when changes have to be made. Proposed changes to any of our APIs go through a strict review process with the entire product development department, where everyone is encouraged to question whether we’re taking the right approach.
At Contentful, we aren’t trying to solve every single user problem on our own. That’s not sensible, and it’s simply not possible. We believe it’s better to focus on adaptability and interoperability with our headless CMS, where our users can adapt Contentful to their individual needs and integrate with the services they already work with. Here are a few ways we do this — and also the “why’s.”
Encapsulated extensions live longer
In the extensibility team, we apply the same principles of stability and interoperability to our UI extensions. UI extensions are sandboxed iframes that allow you to customize the Contentful web app, and they’re the main conduit for users and partners to build new frontend functionalities on top of Contentful.
Even when we make platform upgrades and releases, the extensions you build will keep working. We can guarantee this by encapsulating our extensions. Communication between the web app and the extension is enabled through a secure channel: the UI extensions SDK. As long as the API contract stays valid, we can update the web app and the functionality of the extension won’t be affected.
This is a major difference to the “plug-in” style of extending a system, where updates and changes to the core platform tend to break the functionality of user-created extensions. That’s neither scalable nor future-proof. Enterprise companies often need platforms to be backwards-compatible as well, in order to integrate long-established databases, tools and business procedures.
To make the creation of UI extensions easier and more streamlined, we’ve created tooling and standards for our extensions. We created and open-sourced our Forma36 design system to make it as simple as possible to create extensions with a consistent user experience for the Contentful web app. With the create-contentful-extension CLI, you can build extensions using React and components from Forma36, hot reloading and all required dependencies with zero configuration.
Link up to any API with transformable webhooks
Webhooks are HTTP callbacks that can trigger an action in an external service when data in Contentful is changed, for example, to deploy a production build when content is published or unpublished, or to run a test suite on a CI service when content models are changed. For the most common services used with Contentful, we’ve created templates. For AWS, we support request signatures, allowing you to integrate with over 100 services, including Lambda, S3, SQS, and many more.
Webhooks are usually static and that can be challenging when used to integrate with a third-party API. It often requires additional development, deployment and maintenance of transformation layers to make a webhook compatible with its target service.
To solve this problem, we’ve iterated on webhooks and made them highly customizable. The end result is transformable webhooks, which removes the middle step of translating a webhook’s request into a format an external service can read — making the transformation layer obsolete. You can use transformable webhooks to link to most APIs in the world.
Combine data and content with the GraphQL API
In early 2019, we launched our GraphQL API — and not just because it’s trendy (though we do follow major innovations in technology and want to use the tools developers like to work with). We saw the opportunity, through schema stitching, to achieve a deeper integration of backend data sources with content.
With schema stitching, it’s possible to stitch multiple GraphQL APIs together, merging different data models together and getting the data back as a unified response. For example, you could join together your content model with product data from a tool like Commercetools to pull all product information for an item based on a single identifier referenced in the model. As a developer, this means you just have to talk to one API instead of two.
That’s not to mention the benefit of sheer speed: The core promise of GraphQL is that you can define exactly the data you want returned, as opposed to REST APIs where requests return whole entities. This makes the data transfer smaller overall, which brings down latency, which helps with the experience of your users. The bigger your application is and the higher the traffic, the greater the effect — especially for mobile applications.
Our ecosystem turns design into function
As our users’ implementations of Contentful expand beyond just content management and delivery, we’re preparing for an uncertain future with our modular, extensible product design. But these technical features are only half of the story — they would stop short without our wonderful developer community, our technology partners and the rest of our ecosystem. Without them, we wouldn’t have all the great modules that make our space station functional and habitable.
We want to stay focused on what we can provide best: a stable, adaptable, API-first platform. At the same time, we want you to easily integrate your favorite services and build custom applications with Contentful. Extensibility will be a big part of our architecture and strategy going forward, so keep an eye on this blog for updates.
Have an idea for something to build? Sign up and start!
