Mule-Dev-201 · Domain 2 of 12

Mule-Dev-201 Domain 2: Designing APIs

Designing APIs checks that you can read and write RAML 1.0: resources, nested resources, methods, parameters, request bodies and responses, and the choice between a query parameter and a URI parameter.

Exam weight
8%
Official objectives
3
Estimated questions estimate
~5
Suggested study time estimate
5–7 hrs

About 11 min read Reviewed October 2026

Overview

Designing APIs covers the specification-first part of MuleSoft development. In Anypoint Design Center you write an API specification, usually in RAML 1.0, try it with the mocking service, and publish it to Anypoint Exchange so consumers and implementers work from the same contract. The exam expects you to read RAML fluently and know what each construct means for the requests a client can send.

The section has three objectives. You use REST methods and resources, including nested resources such as /orders/{orderId}/items. You define parameters and responses: query parameters, URI parameters, headers, request bodies, status codes and response bodies with types and examples. You also decide when a value belongs in the URI path and when it belongs in the query string. The questions are short and precise, often showing a fragment of RAML and asking which request is valid or what the specification allows.

How it's tested

Expect RAML fragments of ten to twenty lines followed by a question about valid requests, the response a client receives, or the correct place for a parameter. Some items describe a requirement in words and ask which RAML snippet implements it. Indentation and the colon after each key matter.

  • Read the spec

    Given a RAML fragment, you choose the URL and method that form a valid request, including nested resource paths.

  • Pick the parameter type

    A requirement to filter, sort or identify records leads you to choose between a query parameter and a URI parameter.

  • Define the response

    You choose the RAML that declares a status code, media type, body type or example for a method's response.

Reasoning it through

A specification defines /accounts with a get method and a nested /{accountId} resource with get and delete. A consumer wants every account in Canada. The account ID identifies one resource, so it belongs in the path, but Canada filters a collection, so it should be a query parameter on GET /accounts, for example /accounts?country=CA. DELETE /accounts?country=CA is not defined in the specification, so a strict implementation rejects it.

Objectives 3

Official objectives from the Salesforce outline, in outline order.

2.1 Use REST API methods and resources.Resources, nested resources and HTTP methods in RAML.
What it means
In RAML, resources are keys starting with a slash, such as /orders, and nesting a key such as /{orderId} beneath them creates a child path. Methods are declared under each resource: get, post, put, patch and delete. A method only exists for a resource if the specification declares it there.
What to understand
Map methods to intent: GET retrieves, POST creates, PUT replaces, PATCH partially updates and DELETE removes. GET and DELETE normally have no request body. Nested resources express hierarchy, so /customers/{customerId}/orders lists one customer's orders. Know the RAML header line #%RAML 1.0, the title, version and baseUri keys, and how resource types and traits let you reuse patterns such as pagination across many resources.
How it shows up
A fragment shows several resources, and you identify which request path and method combination the specification supports.
Common confusion
Declaring get on /orders does not declare it on /orders/{orderId}; each nested resource lists its own methods.
2.2 Define REST API parameters and responses.Query parameters, URI parameters, headers, bodies and responses in RAML.
What it means
RAML declares queryParameters and headers under a method, uriParameters under a templated resource, and a body keyed by media type such as application/json. Responses are keyed by status code, and each can declare a body with a type and an example. Data types can live in the specification, in a types section or in a library.
What to understand
Parameters have types and constraints, such as type: integer, minimum, enum, pattern and required: false. A request that breaks a required parameter or type constraint is invalid against the specification, which is what APIkit later uses to return 400. Responses commonly include 200 for reads, 201 for created resources and 204 when there is no body. Examples in the specification feed the mocking service and APIkit's generated responses.
How it shows up
You choose the RAML snippet that makes a parameter optional, sets a default, restricts values or returns 201 with a body.
Common confusion
Query parameters in RAML are required by default unless marked required: false, which surprises candidates who assume optional.
2.3 Identify when and how to define query parameters vs URI parameters.Choosing between path segments and the query string.
What it means
URI parameters are part of the path and identify a specific resource, such as /orders/{orderId}. Query parameters follow the question mark and modify how a collection is returned, for example filtering, sorting, paging or selecting fields.
What to understand
In RAML, a URI parameter is created by naming a nested resource in braces, and it is described under uriParameters. Query parameters are listed under the method with queryParameters. In a Mule 4 implementation the values are read from attributes.uriParams and attributes.queryParams. A good rule: if removing the value changes which resource you mean, it is a URI parameter; if it only narrows or shapes results, it is a query parameter.
How it shows up
A requirement such as filter by status or retrieve one record leads you to choose the parameter type.
Common confusion
Putting filters in the path, such as /orders/status/open, makes a new resource instead of filtering the collection.

High-yield concepts

The terms, rules and formulas this domain turns into questions most often.

  • RAML 1.0 header

    Every RAML file begins with #%RAML 1.0 followed by keys such as title, version and baseUri.

    Remember
    Fragments and libraries use their own header variants.
    Tested as
    Helps identify a valid specification file.
    Trap
    Assuming OAS syntax applies in a RAML fragment.

  • Resource

    A key beginning with a slash that represents an addressable path.

    Remember
    Nesting creates child paths that append to the parent.
    Tested as
    Determines which URLs are valid.
    Trap
    Reading a nested resource as a sibling.

  • Method

    An HTTP verb declared under a resource: get, post, put, patch or delete.

    Remember
    Undeclared methods are not part of the contract.
    Tested as
    APIkit returns 405 for undeclared methods.
    Trap
    Assuming every resource supports every verb.

  • uriParameters

    Describes templated path segments such as {orderId}.

    Remember
    Values are read from attributes.uriParams in Mule 4.
    Tested as
    Identifies one resource in a collection.
    Trap
    Declaring path values under queryParameters.

  • queryParameters

    Describes values after the question mark for a method.

    Remember
    They are required by default unless required: false is set.
    Tested as
    Used for filtering, sorting and paging.
    Trap
    Forgetting the required default.

  • Responses by status code

    A responses block maps codes such as 200 or 201 to bodies and examples.

    Remember
    Examples drive mocks and APIkit stubs.
    Tested as
    Questions ask what a client receives.
    Trap
    Placing the response body under the request body key.

  • Data types and examples

    Reusable type definitions describe JSON or XML shapes; examples show sample values.

    Remember
    Types enable validation; examples enable mocks.
    Tested as
    Appears in parameter and body questions.
    Trap
    Thinking examples enforce validation.

  • Traits and resource types

    Reusable fragments that apply common method or resource definitions.

    Remember
    A trait such as pageable adds the same query parameters wherever applied.
    Tested as
    Recognizing reuse in RAML snippets.
    Trap
    Confusing traits, which apply to methods, with resource types, which apply to resources.

  • Mocking service

    Design Center feature that returns example responses for a specification before implementation exists.

    Remember
    Lets consumers test against the contract early.
    Tested as
    Specification-first questions mention it.
    Trap
    Treating the mock as a deployed implementation.

Side by side

Concepts candidates mix up, compared on the point that decides the answer.

Query parameters vs URI parameters

ConceptMeaningKey differenceCommon trap
URI parameter Path segment that identifies one resource, such as /orders/42 Changes which resource is addressed Using it for optional filters
Query parameter Key and value after ?, such as ?status=open Narrows or shapes a collection response Using it to identify a single record
Header Metadata sent with the request, such as client_id or Accept Describes the request rather than the resource Placing business filters in headers

Methods for writes

ConceptMeaningKey differenceCommon trap
POST Creates a new resource, often returning 201 Server usually assigns the identifier Using it to fetch data
PUT Replaces a resource at a known URI Sends the full representation Assuming it applies a partial change
PATCH Partially updates a resource Sends only changed fields Treating it as identical to PUT

Exam traps

Each trap is an answer that looks right. Learn the clue that should change your mind.

  1. Filter in the path

    What candidates pick
    /orders/status/{status} for filtering orders by status.
    Why it looks right
    It looks tidy and RESTful.
    Why it's wrong
    Each path segment names a resource; a filter on a collection belongs in the query string.

    Clue to watch for Words like filter, search, sort or page.

  2. Optional by default

    What candidates pick
    Assuming a declared query parameter can be omitted.
    Why it looks right
    Many frameworks treat query parameters as optional.
    Why it's wrong
    RAML parameters are required unless marked required: false, so omitting one makes the request invalid.

    Clue to watch for A parameter list with no required key shown.

  3. Inherited methods

    What candidates pick
    Believing /orders/{id} accepts DELETE because /orders declares delete.
    Why it looks right
    Nesting suggests inheritance.
    Why it's wrong
    Methods are declared per resource; the child supports only what it lists.

    Clue to watch for A question asks which request is valid against the fragment.

  4. Examples validate

    What candidates pick
    Thinking an example forces responses to match it.
    Why it looks right
    Examples look like rules.
    Why it's wrong
    Types and constraints validate; examples only illustrate and drive mocks.

    Clue to watch for The stem mentions validation of an incoming request.

  5. PUT for partial change

    What candidates pick
    Choosing PUT to update one field.
    Why it looks right
    PUT is commonly used for updates.
    Why it's wrong
    PUT replaces the whole representation; PATCH is the method for a partial update.

    Clue to watch for The requirement says only change one attribute.

Answer framework

Apply these steps to any RAML snippet or design requirement on the exam.

  1. Trace the indentation to build the full path for each resource, including nested URI parameters in braces and the baseUri prefix where one is declared.
  2. List the methods declared on each resource and treat any undeclared method as invalid for that path.
  3. Decide whether each value identifies a resource, which makes it a URI parameter, or filters or shapes results, which makes it a query parameter.
  4. Check parameter constraints: type, enum, pattern, minimum and whether required: false appears; otherwise treat the parameter as required.
  5. Read the responses block by status code and media type to predict the body, example or code a client receives.

Practice question

A RAML specification declares /products with a get method that has a queryParameters entry category of type string with no other properties. A nested /{productId} resource declares get only. Which request is valid against this specification?

Want more like this? The Mule-Dev-201 practice test has questions for every domain.

Checklist

0 of 10

Tick each one you can do without notes. Your ticks stay in this browser.

Study strategy

Learn RAML by writing it. Open API Designer in Design Center and build a small specification with two top-level resources, one nested resource, a mix of methods, query and URI parameters, and responses with examples. Turn on the mocking service and send requests that you expect to pass and fail; the validation messages teach the required-by-default rule quickly.

Next, read specifications others have published in Exchange and practise predicting valid URLs from them. Cover the right half of a fragment and rebuild the paths from indentation alone. Keep a one-page note of syntax that is easy to forget: required: false, uriParameters placement, responses keyed by number, and media types under body.

Because this section is only 8%, keep the time to about one week of evenings. Link it straight to Building API Implementation Interfaces by running APIkit scaffolding on your own RAML; seeing which flows appear from your resources and methods reinforces both sections at once.

FAQ

How many questions come from Designing APIs on Mule-Dev-201?

Designing APIs carries 8% of the exam weight, which is roughly five of the 60 scored questions. Salesforce does not publish exact per-section counts.

Is OpenAPI (OAS) tested, or only RAML?

The objectives refer to REST API design generally, while the APIkit and consumption objectives name RAML. Study materials focus on RAML 1.0, so learn it well and know that Anypoint also supports OAS specifications.

Do I need to know RAML libraries and fragments?

Know that they exist and what they do: libraries and data type fragments let teams reuse types, traits and resource types across specifications published in Exchange. Detailed authoring of complex libraries is less likely than reading simple ones.

Are RAML query parameters required by default?

Yes. A declared parameter is required unless the specification sets required: false or the parameter name ends with a question mark. This detail shows up in valid-request questions.

Where do I write and test a specification?

API Designer in Anypoint Design Center lets you write RAML, see live documentation and call the mocking service, then publish the specification to Exchange.

Does this section include API security design?

Security schemes exist in RAML, but the exam guide's objectives focus on methods, resources, parameters and responses. Applying security policies is covered in the deploying and managing section.

Other CRM & Business Applications certifications

Where the same subject shows up in other exams. Cards marked "Same subject" open the matching domain.

Test your Domain 2 knowledge

You have practised RAML resources, methods, parameters and responses. Try timed Mule-Dev-201 questions that ask you to read a specification and pick the valid request.

Take the Mule-Dev-201 practice test Check your Mule-Dev-201 readiness

Keep going