liveBook · Manning

Interface definition language

As explained in Microservices Patterns, Second Edition

An interface definition language is a formal language for specifying the operations, data structures, and communication contracts exposed by software interfaces.

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

How Microservices Patterns, Second Edition covers it

How deep it goes
Defines IDL purposes and API-first steps, then outlines AsyncAPI documents and typed message code generation.
Examples
Illustrates a customer event channel linked to a message and payload schema in an AsyncAPI document.
What you can do after
Evaluate/understand how to define service contracts and weigh generated client code against design-time coupling.
How it connects
Connects service API contracts to API-first development, compatibility checking, message schemas, and code generation.

Also explained in

Compare how 2 books explain interface definition language →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Microservices Patterns, Second Edition. The section links point to the parts of the book it draws on.