 |
VOOZH | about |
|
VOOZH | about |
We’re so glad you’re here. You can expect all the best TNS content to arrive Monday through Friday to keep you on top of the news and at the top of your game.
Check your inbox for a confirmation email where you can adjust your preferences and even join additional groups.
Follow TNS on your favorite social media networks.
Become a TNS follower on LinkedIn.
Check out the latest featured and trending stories while you wait for your first TNS newsletter.
Platforms enable DevOps teams to leverage infrastructure and its capabilities and define a set of best practices for security and reliability. Let’s explore how technical leaders and architects can adopt a similar platform mindset for APIs, and what an initial version of an API platform can look like.
A successful DevOps platform stays coherent and efficient in its value propositions while satisfying the need to bring together capabilities for others to build on. Applying this mindset to an API landscape provides consistency for both the technology and the workflows, which radically simplifies the developer experience for API consumers. Here are the requirements that help ensure a successful API platform.
If you ask five teams to design an API for a given problem, it’s pretty much guaranteed that the result will be five different APIs. But an API works as a contract (formal or not) between those who produce and consume it. Being able to clearly define how to solve a functional problem is important to all involved. So you should state the technical contracts so that goals and responsibilities become clear. Here’s an example: “The platform supports GraphQL, its security will be managed via JSON Web Token (JWT) and observability is managed through OpenTelemetry.”
The “paved road” approach clearly defines the contract and determines the default for its criteria. It sets up repeatable, reusable, automated and easy ways for new and old teams to learn what they need. For example, if the majority of teams are developing with Java and Spring Boot, the paved road approach means setting up some application chassis, libraries, code examples and more in advance.
When a field or object that is utilized across an API schema is aligned with its business terminology, this cohesion allows for the use of tools such as automated linters to catch issues as early as possible. API teams often won’t notice this sort of issue because their use cases seem to be singular enough that any divergence would be justified.
Self-service is the answer to scaling and aids in preventing onboarding slowdowns. Documentation, processes and technical tools simplify onboarding. If you must have a meeting, focus it on what adds the most value to the company and project so your teams can operate efficiently and with purpose.
A platform replaces time-consuming discussions, research, pipeline definition and security wrangling with onboarding documentation. It also provides an easy way to bootstrap a new application with all the default trimmings, reducing time to value (TTV) to hours if not minutes. Usage collection and checks automated by the platform can help teams know who is using their part of the platform and act appropriately.
Coherence is an ever-running check. Teams step back and review the solution to see if there are any gaps or issues that can be solved. Features and capabilities grow as the platform evolves over time, but it’s important that they align with stated goals and responsibilities — and the platform contract.
If an API tries to do too much — for example, exposing business capabilities and tailoring its responses for UI applications — it’s possible that the overall experience will be neither cohesive nor coherent. You will have to make some choices, but if the context changes, the platform must react and make the appropriate adjustments.
In the world of the API platform, there is an important distinction to make: Having a single platform doesn’t mean you have a single monolithic type of API. There are important differences to consider among the processes, tools and practices in place and their implementations and usages (for instance, the type of APIs you’ll need to put in place).
An API should serve a specific purpose; otherwise, the consumer experience will degrade. However, the technology and processes can be reused or adapted. The principles of coherence and cohesion are valid for any APIs at the same level of semantics. Does a frontend application have the same API needs as a CLI tool or another service in the domain? You could try to implement a one-size-fits-all approach, but over time, the needs of your teams will diverge, and frustration will grow.
To accommodate various use cases, you can use layered types of APIs. These layers can serve different purposes by means of a form of abstraction. Companies that have chosen this path are seeing increased velocity as well as the ability to iterate without as much coordination. This approach can drive consistency for producers and consumers alike. Also, a move to a unified, federated approach can enable you to scale APIs, reuse infrastructure and ship code faster. Let’s see what that looks like for these types of APIs:
Here is an example of how an API platform could look with an architecture that combines multiple GraphQL APIs into a graph of graphs that client teams can query from a single endpoint.
In this diagram, the API platform concept is applied twice, in customer experience and domain API contexts. It’s possible to have linting rules, schema review processes, authorization and authentication that vary based on requirements. Yet because the standards of platform engineering are followed, the automation and repeatability inherent in this approach simplify the management of the two scopes.
With the right setup, you can “link” domain entities from various domains. For example, the concept of `User` would likely be present in the `User` domain and also in the `Order` domain. While both are talking about the same “User,” the perspectives of these domains could be different — one with all the profile information (e.g., names, addresses, marketing preferences, loyalty), and the other with data necessary to fulfill an order (e.g., names, billing address, shipping address).
On the security front, the API platform unifies how consumers can leverage resources with authentication and authorization aspects. In the context of a domain API backed by a graph of graphs, each domain can uniformly express who can access which resource, with a GraphQL gateway performing enforcement at runtime.
The requirements for your platform will evolve along with the requirements of your applications. A platform therefore should always evolve based on the needs of its users, and in many ways is a product in and of itself.
