Workshops: Agentic Engineering Practices

API-First Design with AI Agents: OpenAPI & GraphQL Workshop

When agents write the implementation, the API contract becomes the most important artefact your team still designs deliberately, with the agent as sparring partner. In this workshop your team designs OpenAPI and GraphQL schemas with AI agents, derives contract tests, mocks and client SDKs from them and learns to evolve APIs without surprising consumers.

Who is this workshop for?

  • API designers and backend teams who own public or internal APIs
  • Frontend and mobile teams who want to shape the contract early
  • Platform and integration teams responsible for API guidelines
  • Software architects introducing API-first across several teams
  • Product owners of partner interfaces and developer products

What you will take away

  • Draft and review OpenAPI and GraphQL schemas with an agent against your own API style guide.
  • Lint schemas automatically and have the agent fix rule violations before review.
  • Generate mock servers, client SDKs and server stubs from the contract and keep them in sync.
  • Build contract tests that catch drift between specification and implementation.
  • Detect breaking changes in pull requests and plan versioning and deprecation cleanly.

Agenda

  1. Module 1

    Contract first, code second

    • Why the contract matters more once agents write the code
    • REST with OpenAPI, GraphQL or event-driven with AsyncAPI: what fits when
    • Turning domain language into resources, types and operations
  2. Module 2

    Designing with the agent

    • Exercise: design an API for one of your use cases with Claude Code, Cursor or GitHub Copilot
    • Your style guide as agent instructions: naming, pagination, errors, filtering
    • Linting with Spectral or GraphQL schema rules, fixes by the agent
  3. Module 3

    From contract to artefacts

    • Mock servers so frontend work can start immediately
    • Client SDKs and server stubs with openapi-generator or similar tools
    • When generated code beats agent-written code
  4. Module 4

    Contract tests

    • Consumer-driven contracts with Pact
    • Property-based API tests derived from the spec, e.g. with Schemathesis
    • Letting the agent implement against failing contract tests
  5. Module 5

    Evolving APIs

    • Detecting breaking changes automatically in the pull request
    • Versioning, deprecation notices and sunset periods
    • Changelogs and migration notes for consumers, drafted by the agent

Why API-first pays off more with coding agents

Coding agents implement endpoints and resolvers at high speed. That speed turns a weak contract into a problem: inconsistent naming, improvised error formats and accidental breaking changes spread across services before anyone notices.

A machine-readable contract gives the agent a precise target and gives your team one place to review design decisions. Implementation, tests, mocks, SDKs and documentation follow from it, and the agent can check its own work against the specification.

What we cover per API style

We focus on the styles your organisation actually uses:

  • REST: OpenAPI, resource modelling, error formats such as Problem Details, pagination and idempotency
  • GraphQL: schema design, nullability, connection-based pagination, evolution without versions
  • Events: AsyncAPI for message-based interfaces as an outlook
  • Governance: shared style guides, linting in CI, review of contract changes

Your API as the exercise

Participants bring an API they are planning or one that badly needs a cleanup. By the end of the day you have a reviewed contract, a lint configuration with your rules, a mock server and the first contract tests. Remote or on-site, in English or German, with neooutput AI Code Engineers.

Frequently asked questions

Should we generate SDKs or let the agent write them?

For stable, widely used APIs we usually recommend generators because they are deterministic and repeatable. Agents add value in the thin, idiomatic layer on top and in keeping examples and docs current.

Can we introduce API-first for an existing API?

Yes. The agent derives a first schema from existing code and example requests, which you clean up and declare the source of truth. Contract tests then keep code and spec aligned.

Do you also cover gRPC?

The focus is on OpenAPI and GraphQL, but the principles apply equally to gRPC and Protocol Buffers. If gRPC is central for you, we adapt the exercises.

Workshop

Get in touch

Which API should your team design properly before the agents build it?

Tell us roughly how many people will join and pick dates that work – we will get back to you within 24 hours with a proposal for content, format and schedule.

Prefer to talk first?

15 minutes, free and without obligation – with our AI Trainers and AI Code Engineers.

Book a call for free (opens in new tab) +49 761 519 751 50 (24/7)

Request a training / workshop

Workshop: API-First Design with AI Agents: OpenAPI & GraphQL Workshop · 1 day

Dates that work for you (optional)

Suggestions about 2 weeks ahead – pick as many as you like

Reply usually within 24 hours · jocapps is ISO 27001 certified · Privacy