Wirespec your APIs

What is Wirespec?

Wirespec is a small, human-readable language for describing APIs. You write the contract once, in a .ws file, and it becomes the single source of truth for every team that builds or calls the API:

type Todo {
  id: Integer,
  title: String,
  done: Boolean
}

type ApiError {
  message: String
}

endpoint GetTodo GET /todos/{id: Integer} -> {
  200 -> Todo
  404 -> ApiError
}

From the contract, Wirespec generates typesafe, dependency-free code for each side of the API: TypeScript for the frontend, and Kotlin, Java, Python, Rust or Scala for the backend. It can also publish the contract as OpenAPI or Avro, and turn an existing OpenAPI, AsyncAPI, Avro or GraphQL specification into Wirespec.

Wirespec is built around three ideas, each explained in the documentation:

• Contract first: agree on the interface before anyone implements it, independent of language or framework.
• Generate code: derive models, endpoints and clients from the contract instead of writing them by hand.
• Validate the implementation: test against the same contract with generated test data and mocks.

Get started

Try Wirespec in the Playground, no installation needed. To use it in a project, Getting Started has a guide for frontend engineers, backend engineers, API designers and teams that already have a specification.

Documentation

Topic	What you will find
Language	The syntax: types, endpoints, channels, RPCs, annotations and default values
Emitters	The code and specifications generated for each target
Plugins	Installing and configuring the CLI, Gradle, Maven and npm plugins; IR extensions
Converters	Converting existing specifications to Wirespec
Integration	Spring, Jackson, kotlinx.serialization, Avro, WireMock, Kotest and model builders
IDE	The IntelliJ IDEA and VS Code plugins, and the language server for other editors
Architecture	How the compiler works, for contributors and extension authors

Examples

The examples directory holds complete projects that use Wirespec with Maven, Gradle, npm, Cargo and sbt.

Contributing

Contributions are welcome: CONTRIBUTING.md explains how to propose a feature, build the project and open a pull request.