Declarative API design explained

We’ve been sharing insights recently into declarative API management and the advantages of a declarative infrastructure. But if you’re wondering where API design come into all this, this is the article for you. Today, we’re exploring what constitutes a declarative API, its principles, and how it differs from other API design paradigms. Brace yourself for everything you need to know about declarative API design, including essential tools to turn the theory into practice.

What is declarative API design?

Declarative API design is an approach to building APIs that focuses more on what you need to achieve than how you need to get there. It enables your APIs to serve declarative clients in an efficient and consistent manner, making it a key part of designing valuable APIs. When the client expresses what it wants to achieve, the API doesn’t require it to orchestrate a sequence of operations to get there because it is designed to accept declarative expressions. You shape the API interface so that the only (or primary) way to use it is declaratively.

Benefits and challenges of declarative API design

Declarative API design offers several distinct advantages, particularly as more and more organizations configure their systems using declarative principles. It means your APIs become more usable for modern scenarios and tooling, such as the need to handle the complexity of orchestrating multi-resource, interdependent cloud environments.

Other advantages of a declarative approach to API design include simplified client code, a reduction in API misuse (through abstracted operational details), greater idempotency, and predictable results. Easier versioning and backwards compatibility are the icing on the cake.

Achieving these benefits does come with some challenges. You’ll need sophisticated backend logic to interpret declarations, plus you may find debugging harder as you have less clarity on the “how” of what’s happening. There’s also the potential for infinite loops if field ownership (client vs server) isn’t clear.  

Remember that, depending on your use case, there may be instances where an imperative workflow is necessary instead of a declarative one (more on declarative vs imperative API design below).

Key characteristics of declarative API design

Declarative API design involves intentionally building APIs that are usable by declarative clients. This encompasses several key characteristics: 

• APIs are outcome-focused and able to work with clients making a declaration of desired results, rather than a specific string of actions outlining how to achieve those results.
• Interactions are state-based, with the client sending the desired state and the server having to compute the changes needed.
• Imperative logic is reduced, with a declarative design approach helping automate operations instead.
• A structured schema, such as JSON, YAML. GraphQL or domain-specific language, may be used as well.

A common example of this in practice is UI definition APIs. With these, the client describes the layout components, while the rendering engine decides how to build the UI.

How does declarative differ from imperative API design?

Declarative APIs have several fundamental differences to imperative APIs. Embracing server-side automation and abstraction, declarative APIs tend to be more easily maintainable and scalable. They can also support you to optimize the API products you offer, aligning more naturally with modern tooling and workflows. This makes it easier for declarative clients and automation systems to use your API products effectively.

The key differences between declarative vs imperative APIs are as follows:

Examples of declarative API design include Terraform-style APIs, desired-state config APIs, and some resource controllers. An example of an imperative API design is a REST endpoint that requires ordered calls, with each request following a defined, step-by-step structure. 

What frameworks support declarative API design?

Some of the most common framework examples when it comes to supporting declarative API design are infrastructure and cloud resource platforms such as Kubernetes, Terraform, CloudFormation (AWS), and ARM/Bicep (Azure). These platforms use declarative models natively, demanding APIs that accept a desired-state representation.

The Kubernetes API, for example, enables clients to submit YAML/JSON manifests that declare the desired state. Controllers then drive reconciliation to achieve this.

While we’re looking at examples, this video is an excellent showcase of how to declaratively design, compose and publish GraphQL APIs from REST and GraphQL data sources using a no code approach.

Configuration management ecosystems also encourage resource-centric, state-based API design. Examples include Pulumi, which pushes a declarative desire-state model while using general-purpose languages, and Ansible, which operates declaratively (though its executed imperatively behind the scenes). 

Workflow and state reconciliation frameworks offer building blocks for creating API servers that behave declaratively. Tyk Operator is an example of this, defining Custom Resource Definitions (CRDs) that represent Tyk Gateway and Tyk Dashboard configuration objects in a desired-state form (YAML/JSON). You apply a CRD (for example, an API definition), then Tyk Operator reconciles it using a reconciliation loop pattern. The emphasis is on you taking care of the descriptive part to say what you want (API definitions, policies, gateways, and so on), while Tyk Operator handles how to execute those changes.

A range of low-code/no-code platforms also consume APIs declaratively, with a leading example being the Salesforce Metadata API. In addition, while GraphQL isn’t inherently declarative, clients specify the shape of the data they need and servers often adopt resolver patterns that align with a desired-state approach. 

Does declarative API design improve maintainability?

Yes, declarative API design generally supports easier maintainability. When you design a declarative API, you’re shifting complexity away from clients to the API implementation. This reduces client orchestration and coupling, providing a structured approach to better maintainability. 

How does declarative design improve consistency?

One of the benefits of using a declarative model is greater consistency. This is because, with declarative design, you shift control from clients to server. This ensures the desired outcome is applied uniformly, regardless of who or what is making the request. The declarative API makes outcomes predictable and repeatable, ensuring consistency of response in line with the API contract. 

Factors underpinning this greater consistency include:

• Centralized logic, with the server determining how to achieve the declared state, so that the same rules and workflows apply to all clients.
• Uniform state representation, with the client’s expression of a desired state reducing variability in inputs and interpretations.
• Idempotency, where applying the same desired state always results in the same system state. This eliminates inconsistencies resulting from retries and partial updates.
• Reduced client-side orchestration, resulting in less chance of divergent behavior between clients.
• Automatic drift correction, with current and desired state reconciliation keeping everything consistent over time.

Is declarative API modeling better for scaling?

Yes, absolutely. Declarative API modeling underpins scalability, so you can map out your business growth trajectory and get there more smoothly. The automation and consistency associated with a declarative design approach and its stable contracts are a key part of this. They simplify client behavior while centralizing complexity.

Scalability is achieved at multiples levels with declarative design. These include:

• Client scalability:  Clients submit a desired state and rely on a stable contract, with new clients (or tools, or teams) able to integrate without learning complex workflows. As there are fewer client-side differences, less coordination overhead arises as you scale.
• Operational scalability: As the server owns orchestration, retries, ordering, and reconciliation, you can implement batching, async processing, rate limiting, and internal optimization without breaking clients.
• Organizational scalability: Declarative models work well with automation, GitOps, CI/CD, and policy engines, so teams can organize and evolve implementations independently while maintaining consistency.
• Failure and retry scalability: Idempotent, state-based interactions tolerate retries and partial failures, which becomes critical at scale, where failures are frequent.
• Ecosystem scalability: As declarative APIs integrate naturally with tooling (operators, controllers, IaC, policy systems, and so on), you need less custom glue code as your systems grow.

While these benefits support scalability, you’ll need to validate the advantages of declarative API design for your individual business case. That’s because there are also trade-offs to consider. For example, as you abstract complexity away from clients, server complexity increases, with reconciliation logic, diffing, and state management all calling for more sophisticated backend design. You may also find that latency is higher, with declarative APIs converging asynchronously rather than responding immediately. There are also instances where the fine-grained, real-time control offered by an imperative API design approach may be a better fit (such as for procedural or transactional use cases).

Generally, declarative API modelling scales better for complex, multi-resource automated systems, so can suit large enterprises well.

How are schemas used in declarative APIs?

Schemas are central to declarative APIs. You use them to define the contract for the desired state, including allowed fields, data types, defaults, and constraints. More than

This enables the system to consistently interpret, validate, and reconcile client intent. By enabling validation before execution, the schema prevents divergent behavior and improves reliability, comparing the desired state to the actual state and reconciling the two.

Schemas define the response structure, as well as applying to requests. This often includes the current state, observed state, status or conditions, errors, and validation feedback. This ensures predictable, consistent responses across clients and tools, with machine readable schemas also enabling tools to generate clients and UIs, validate configs offline, apply policy checks, and support GitOps and CI/CD workflows.

The other factor to consider here is that because schemas are explicit, APIs can add optional fields, deprecate fields safely, and version schemas independently. This can render it easier to evolve your APIs without breaking clients.

What are examples of declarative API tools?

There are excellent tools available to help with your declarative API design. Some examples of declarative API tools include: 

• API contract and schema design tools that define the declarative contract, formalize the desired state, enforce consistency, and enable automation: OpenAPI Specification, JSON Schema, GraphQL SDL, ASyncAPI.
• State-based reconciliation frameworks that help you implement server-side declarative behavior, providing reconciliation, diffing, idempotency, and drift correction: Kubernetes, Kubebuilder, Crossplane, Kopf.
• Infrastructure as code and configuration ecosystems that shape APIs around stable resource schemas: Terraform, Pulumi, AWS CloudFormation. Read more here about infrastructure as code.
• Policy, validation, and governance tools to enforce transparent rules on declarative inputs, ensuring they’re valid, secure, and compliant before execution: Open Policy Agent, Gatekeeper, Kyverno, Spectral.
• Automation and GitOps tools for consuming declarative APIs at scale while reinforcing declarative workflows and consistency across environments: Argo CD, Flux, CI/CD pipelines.
• Testing and lifecycle tools to ensure declarative contracts remain stable: Dredd, Schemathesis.

The tools that will serve you best will depend on your use case and infrastructure, so be sure to research them thoroughly before committing. 

On the subject of tools that support declarative API design, did you know that Tyk Sync enables you to manage API configurations declaratively using version-controlled files? It enables GitOps workflows by maintaining API configurations as code, which you can version and deploy through CI/CD pipelines. 

Tyk Sync is part of Tyk’s flexible, composable, and highly extensible API management solution, designed to work with every protocol and power your business in the AI era.  To find out more about our modular solution, contact the Tyk team.