# API specifications, mocking and design-first development

*MuleSoft Integration Foundations Study Guide · Explain the common technical complexities and patterns in integration development · Last updated November 2, 2026 · https://www.certifyforce.com/study-guide/mulesoft-integration-foundations/technical-complexities-and-patterns-in-integration-development/api-specifications-mocking-and-design-first-development*

What an API specification is and why designing it first pays off: the languages API Designer supports, the mocking service that lets consumers try an API before code exists, and sharing one contract through Exchange, Studio and API Manager.

- Certification: Salesforce MuleSoft Integration Foundations
- Exam section: Explain the common technical complexities and patterns in integration development
- Study guide: https://www.certifyforce.com/study-guide/mulesoft-integration-foundations

**Official exam objective:**

> Describe the purpose of an API specification and the benefits of following a design-first approach to API development.

## What the exam expects

- Explain the purpose of an API specification as the structural plan, or contract, of an API.
- Describe the benefits of a design-first (spec-driven) approach, including the time it costs and the rework it saves.
- Name the specification languages API Designer supports.
- Explain how the mocking service lets consumers try an API before any implementation exists.
- Describe how one specification is shared through Exchange, Studio and API Manager.

Key terms:
- **API specification**: a plan of how the API should look structurally, like a blueprint of a house.
- **Design-first (spec-driven development)**: designing and reviewing the specification before writing implementation code.
- **API Designer**: the Design Center web UI for writing specifications and RAML fragments.
- **Mocking service**: a continuously running service that returns the responses defined in a specification.
- **Behavioral headers**: request headers that change how the mocking service responds.

## Key facts

| Fact | Detail | Source |
|---|---|---|
| Spec-driven time cost | Adds two to four weeks; can save months or years | [API spec](https://www.mulesoft.com/resources/api/api-spec) |
| RAML versions | 0.8 or 1.0 (specs and fragments) | [API Designer](https://docs.mulesoft.com/design-center/design-create-publish-api-specs) |
| OAS versions | 2.0 or 3.0 | [API Designer](https://docs.mulesoft.com/design-center/design-create-publish-api-specs) |
| AsyncAPI versions | 2.0 and 2.6 | [API Designer](https://docs.mulesoft.com/design-center/design-create-publish-api-specs) |
| Mock responses | Status codes and example payloads from the spec | [Mocking service](https://docs.mulesoft.com/design-center/design-mocking-service) |
| Mock prerequisites | At least one endpoint, each with at least one method | [Mocking service](https://docs.mulesoft.com/design-center/design-mocking-service) |
| MS2-Delay maximum | 10000 ms | [Behavioral headers](https://docs.mulesoft.com/design-center/apid-behavioral-headers) |
| Default mock status code | The minimum code defined for the method | [Behavioral headers](https://docs.mulesoft.com/design-center/apid-behavioral-headers) |

## Check yourself

- Why must an endpoint have at least one method before you can mock it?
- What happens to a shared public mocking URL if you disable and re-enable it?
- When the mock receives a request with no behavioral headers, which status code does it return?
- Which language must an API fragment use in API Designer?

## Sources

- [Choosing a great API spec saves time and hassle](https://www.mulesoft.com/resources/api/api-spec)
- [What is API design?](https://www.mulesoft.com/api/what-is-api-design)
- [Getting Started with API Designer](https://docs.mulesoft.com/design-center/design-create-publish-api-specs)
- [Simulate API Calls with the Mocking Service](https://docs.mulesoft.com/design-center/design-mocking-service)
- [Add Behavioral Headers to Simulated API Calls](https://docs.mulesoft.com/design-center/apid-behavioral-headers)
- [Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 4 linked practice questions, and unlimited timed mock exams are included with the MuleSoft Integration Foundations pack (USD $19): https://www.certifyforce.com/practice-exams