An interface definition language (IDL) specifies a software interface as a precise, machine-readable contract. In a microservice architecture, services and clients are developed and deployed independently, so they are not compiled together. An incompatible API change can therefore reach production without a shared compiler catching it. An IDL makes the contract explicit and supports automated compatibility checks. section 8.1.2 section 8.3.5
The contract depends on the communication mechanism. An HTTP API specifies URLs, verbs, and request and response formats; a messaging API specifies channels, message types, and payload formats. OpenAPI can define REST APIs, while AsyncAPI describes messaging APIs. section 8.1.2 section 8.3.5
An IDL can serve as a single source of truth for:
- Generating client and server code, including message classes and serialization code where supported. section 8.1.2 section 8.1.6
- Documenting and validating APIs and checking changes for compatibility. section 8.1.2
Use an API-first workflow: write the interface definition, review it with client developers, iterate, and then implement the service. Compatibility still needs active management. When a change breaks clients, the service will typically need to support old and new versions until clients have upgraded. section 8.1.2 section 8.4
For asynchronous messaging, a payload schema alone is not the whole contract. AsyncAPI also describes channels, message types, and whether a service sends or receives messages. Its documents use JSON or YAML and can describe how a service interacts with the messaging system. section 8.3.5
Listing 8.3 An excerpt from an AsyncAPI document that defines a service publishing events such as CustomerCreatedEvent to the com.example.Customer channel.
channels:
com.example.Customer:
address: com.example.Customer
messages:
com.example.CustomerCreatedEvent:
$ref: "#/components/messages/com.example.CustomerCreatedEvent"
...
messages:
com.example.CustomerCreatedEvent:
headers:
$ref: "#/components/schemas/HeadersNotDocumented"
payload:
schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
schema:
$ref: "#/components/schemas/com.example.CustomerCreatedEvent"
name: com.example.CustomerCreatedEvent
title: com.example.CustomerCreatedEvent
...
components:
schemas:
com.example.CustomerCreatedEvent:
title: CustomerCreatedEvent
type: object
properties:
id:
type: string
examples:
- id: string
operations:
io.eventuate.exampleapp.events.publisher.CustomerEventPublisherImpl:
action: send
channel:
$ref: "#/channels/com.example.Customer"
messages:
- $ref: "#/channels/com.example.Customer/messages/com.example.CustomerCreatedEvent"
This AsyncAPI excerpt connects a customer event channel to a message and its payload schema. section 8.3.5
Protocol Buffers and Avro use typed IDLs to define message structures and generate serialization code. Their binary formats are compact and efficient but require additional tooling. Code generation is convenient, although generating client DTOs from an entire API can create unnecessary design-time coupling; writing them by hand can reduce that coupling at the cost of more work. section 8.1.6 section 8.4

