# RAML responses, examples and the mocking service

*MuleSoft Developer Study Guide · Designing APIs · Last updated October 28, 2026 · https://www.certifyforce.com/study-guide/mulesoft-developer/designing-apis/raml-responses-examples-and-the-mocking-service*

How RAML 1.0 nests responses, bodies and media types, how types and examples (inline, .yaml files and NamedExample fragments) must match, and which response the API Designer mocking service returns with and without behavioral headers.

- Certification: Salesforce MuleSoft Developer
- Exam section: Designing APIs
- Study guide: https://www.certifyforce.com/study-guide/mulesoft-developer

**Official exam objective:**

> Define REST API parameters and responses.

## What the exam expects

- Declare a method's response in RAML 1.0 with the right nesting: `responses`, status code, `body`, media type, then `type` or `example`.
- Fix "Payload media type is mandatory" with a local media type key or a root `mediaType`.
- Write types and examples that validate: required versus optional (`?`) properties, `additionalProperties`, strict YAML typing in `enum`, and examples kept in external files.
- Predict which status code and example the mocking service returns, and pick the behavioral header that changes it; know who can call the mock and when.
- Key terms: **media type** (the key such as `application/json` that a payload is declared under); **`mediaType`** (root node that sets the default media type); **NamedExample** (a RAML fragment whose keys name each example); **mocking service** (an Anypoint Platform feature that answers calls with the specification's responses); **behavioral header** (an `MS2-*` request header that changes the mock's behavior).

## Key facts

| Fact | Detail | Source |
|---|---|---|
| Response nesting | `responses:` then status code then `body:` then media type then `type` | [Common Problems Found in RAML 1.0 API Specifications](https://docs.mulesoft.com/design-center/design-common-problems-raml-10) |
| Missing media type | "Payload media type is mandatory"; fix locally or with root `mediaType` | [Common Problems Found in RAML 1.0 API Specifications](https://docs.mulesoft.com/design-center/design-common-problems-raml-10) |
| Optional property | Trailing `?`, as in `age?: integer` | [Common Problems Found in RAML 1.0 API Specifications](https://docs.mulesoft.com/design-center/design-common-problems-raml-10) |
| `additionalProperties` | `true` by default | [Common Problems Found in RAML 1.0 API Specifications](https://docs.mulesoft.com/design-center/design-common-problems-raml-10) |
| Several external examples | Always the `examples` facet | [Guide to Defining Examples in RAML 1.0](https://docs.mulesoft.com/design-center/design-named-examples) |
| NamedExample fragment | A key names each example; values are not at the root | [Guide to Defining Examples in RAML 1.0](https://docs.mulesoft.com/design-center/design-named-examples) |
| Mock default | Lowest status code defined for the method | [Add Behavioral Headers to Simulated API Calls](https://docs.mulesoft.com/design-center/apid-behavioral-headers) |
| `MS2-Status-Code` | Filters the defined status codes | [Add Behavioral Headers to Simulated API Calls](https://docs.mulesoft.com/design-center/apid-behavioral-headers) |
| Public mock URL | No authorization header; re-enabling generates a different URL | [Simulate API Calls with the Mocking Service](https://docs.mulesoft.com/design-center/design-mocking-service) |

## Check yourself

- Why must `MS2-Status-Code` list two codes when it is combined with `MS2-Error-Rate`?
- When no `MS2-Error-Level` is sent, which error ranges may the mock use?
- What is the maximum value `MS2-Delay` accepts?
- How can the lifetime of a mocking service public URL be limited?

## Sources

- [Common Problems Found in RAML 1.0 API Specifications](https://docs.mulesoft.com/design-center/design-common-problems-raml-10)
- [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)
- [Guide to Defining Examples in RAML 1.0](https://docs.mulesoft.com/design-center/design-named-examples)
- [Building, Implementing, and Testing a REST API](https://docs.mulesoft.com/apikit/latest/apikit-4-implement-rest-api)
- [Getting Started with API Designer](https://docs.mulesoft.com/design-center/design-create-publish-api-specs)

## About the full unit

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