Contract First API

API Contracts with TypeSpec

1. Interoperability

Interoperability is a key property for protocols or systems that must endure for years. Standard APIs that are technology agnostic surviving obsolete technologies allows the standard to survive such initial implementations.

Aerospace systems, defense, banking, open data and public administration are only a few examples where such standards are a real need.

2. Contract First APIs

In such scenarios, contract-first development is a need avoiding any technical vendor locking to preserve maximum interoperability for years.

REST APIs over JSON are nowadays the base to build upon describing such contracts using OpenAPI v. 3.2.0.

3. Tooling

But writing OpenAPI by hand is tedious and error prone. Are there better tools for that? Yes: TypeSpec is a DSL created to raise the abstraction level and to focus on describing the contract as concise and precise as possible.

Patterns like pagination are elegantly described only once and reused in the contract. Signatures of operations for resources are cleanly described and documented.

4. Vision

At Structura, we are embracing Contract-First development and TypeSpec. Not only because we are firmly convinced of the values of contract-first but also about ensuring interoperability among different technologies we use.

For example: We have dotNet code generators for backends. Now creating a Java experimental backend and later on also a frontend generator for Angular to be connected to the backends.

We want our Angular generator to consume a neutral API. In the extreme, the Angular developer does not need to know if the backend implementation is Dotnet, Java, Go. Does not need to know either if its database is MongoDB or a relational database.

This allows the team to change the underlying technology later if the requirements change.

Consequences: the dotnet and java backends will converge and implement the same Rest API.

Advantages:

  1. We can implement benchmarks to compare performance using the same hardware base and decide about which one to use based on the requirements and scenarios.
  2. We can add a third implementation in Go or Rust later on if needed. The client will not change.
  3. Standarization: common patterns like error handling, pagination, search and ordering should not change from end-point to end-point and should be standardized.
  4. Having a coercive contract in a formal representation we can use code generation to derive client-side proxies or server-side skeletons implementations. Also LLMs generating code will have clear guidelines about if the proposed implementation is compliant or not.

5. Implementation Roadmap

Therefore to implement this vision, we are taking the following actions:

  1. Expose a TypeSpec generator at Structura. From a given conceptual model, we are able to derive a default API contract expressed in Typespec. For sure, many design choices are still possible, but we can apply sensible defaults and provide generation options when needed.
  2. Document and version such API for interoperability and long-term support.
  3. Converge the API in the dotnet and java implementations to fully implement the contract prescribed by the Typespec generator. Same API standards in both generators, same design choices as generation options if needed.
  4. Extend to new languages or frameworks based on customers’ needs following the same baseline for the contract.

We will love to have your feedback on this. Please test our TypeSpec and backend generators and let us know what you think. Help us to make it useful for you, the final user.

References

  1. Three common scenarios for leveraging the OpenAPI Specification. Pedro J. Molina - 2017.
  2. Typespec. Microsoft - 2026.