OAS & Spec-First API Design (Course #oas-design)
For developers, BAs, architects.
By the end, you can
By the end of this course, you will be able to author, mock, scaffold and govern OAS 3.x specifications so that partners onboard in days against contract-tested, Exchange-published APIs.
Running case study
Vela Mobility aggregates parking and transit operators behind partner-facing APIs documented today in PDFs and wikis; integrations start as email threads and end in breakages. A self-service developer portal makes OAS 3.x the single source of truth — mocked before coding, governed in Exchange. You redesign their flagship booking API spec-first.
Programme every line is something you do
6 modules · 11 topics · in course-flow order
-
Module 1
Anatomy of an OAS Document
Objective. Structure a complete OAS 3.x document for the booking API: paths, components, schemas, securitySchemes.
- Structure an OpenAPI document: 2.0 vs 3.x deltas, servers, paths, components/schemas, securitySchemes
-
Module 2
RAML 1.0 Meets OAS 3.x
Objective. Convert Vela's RAML 1.0 heritage to OAS 3.x without losing examples, traits or security schemes.
- Convert between RAML 1.0 and OAS 3.x with tooling, then repair whatever automation drops
- Weigh trade-offs: resourceTypes/traits vs components, includes vs $ref, surrounding ecosystems
- Choose per context: greenfield partner APIs, internal APIs, specs destined for API Manager policies
-
Module 3
Mock First, Code Second
Objective. Iterate the booking design in API Designer and confront the mocking service with real consumer feedback.
- Design iteratively in Design Center/API Designer: live validation, inline docs, spec snippets
- Validate early with API Console and the mocking service: turn examples into executable expectations
-
Module 4
Spec to Running Skeleton
Objective. Generate runnable APIkit flows from the OAS spec in Studio/ACB and gate merges on automated contract tests.
- Generate APIkit flows from OAS in Studio or Anypoint Code Builder, operation by operation
- Enforce the contract in CI: status codes, schemas and examples asserted against the spec
-
Module 5
Style Guides That Enforce
Objective. Publish the versioned spec to Exchange and enforce a style guide checklist that rejects nonconforming designs.
- Publish specs to Exchange with docs, examples, versions and lifecycle states
- Apply review checklists and style guides: naming, pagination, RFC 7807 error models, versioning rules
-
Module 6
Lab: Booking API End to End
Objective. Carry the booking API through the full loop: OAS 3.0 design, mock, scaffold, publish to Exchange.
- Design an OAS 3.0 API, mock it with the mocking service, scaffold flows and publish it to Exchange
References & Official Documentation every claim above has a source
Module 1
- JSON Schema — objectSpecification
- OpenAPI Specification v3.1.1Specification
Module 2
Module 3
- Getting Started with API DesignerMuleSoft Docs
- Simulate API Calls with the Mocking ServiceMuleSoft Docs
Module 4
- APIkit for REST Scaffolding ReferenceMuleSoft Docs
Module 5
- RFC 9457 — Problem Details for HTTP APIsSpecification
- Anypoint API Governance OverviewMuleSoft Docs