How to Design a REST API in Anypoint Code Builder (OpenAPI + VS Code + Exchange)

Alex Martinez
Jul 14
3 min read

Whether you’re new to MuleSoft or finally starting to explore Anypoint Code Builder (ACB), this post will walk you through designing a full REST API specification using OpenAPI 3.0 — directly inside VS Code, with no XML or flows yet.

By the end, you’ll be able to:

Define a reusable OpenAPI spec for a To-Do API
Mock and test the endpoints inside ACB
Publish the spec to Anypoint Exchange so your team can reuse or scaffold flows from it later

Let’s build the foundation for your next MuleSoft project — the right way.

🎥 Prefer video? Watch the full tutorial here:

🛠️ What You’ll Need

New to ACB? Read our Getting Started guide first.
Anypoint Platform account to publish to Exchange.

🧪 What We’re Building

We’re designing a To-Do Task Management API that supports full CRUD operations for /tasks:

GET /tasks to list tasks with optional filters
POST /tasks to create a task
GET /tasks/{taskId}, PUT, and DELETE for individual task management
A schema for Task and a separate input model TaskInput

If you want to follow with the YAML file, you can check it out here.

🧑‍💻 Step-by-Step API Design in ACB

1. Create a New OpenAPI Spec

From the ACB Welcome screen, choose "Design an API", then select:

Type: API Specification
Language: OpenAPI 3.0 (YAML)
Project name: todo-task-api

You don’t need to log into Anypoint Platform just yet.

2. Fill Out the API Info Block

Update the metadata like this:

info:
    version: 1.0.0
    title: To-Do Task Management API
    description: A simple API for managing to-do tasks. Supports full CRUD operations for tasks in a single-user context.

This info will be displayed in Exchange later — so make it clear and helpful.

3. Define Your Endpoints

Start with the /tasks resource and support:

GET with optional query parameters (completed, dueDate)
POST with a JSON request body

paths:
    /tasks:
        get:
            summary: List all tasks
            description: Retrieve a list of all tasks, with optional filtering by completion status and due date.
            parameters:
                - in: query
                  name: completed
                  schema:
                    type: boolean
                  description: Filter tasks by completion status (true or false)
                - in: query
                  name: dueDate
                  schema:
                    type: string
                    format: date
                  description: Filter tasks by due date (YYYY-MM-DD)
            responses:
                "200":
                    description: A list of tasks
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/Task"
        post:
            summary: Create a new task
            description: Add a new task to the to-do list.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TaskInput"
            responses:
                "201":
                    description: Task created successfully
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Task"

Then add the /tasks/{taskId} resource with GET, PUT, and DELETE methods.

Make sure to handle the URI parameter.

    /tasks/{taskId}:
        parameters:
            - in: path
              name: taskId
              required: true
              schema:
                  type: string
        get:
            summary: Get a task by ID
            description: Retrieve a specific task by its unique ID.
            responses:
                "200":
                    description: Task details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Task"
                "404":
                    description: Task not found
        put:
            summary: Update a task
            description: Update an existing task by its ID.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TaskInput"
            responses:
                "200":
                    description: Task updated successfully
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Task"
                "404":
                    description: Task not found
        delete:
            summary: Delete a task
            description: Remove a task from the list by its ID.
            responses:
                "204":
                    description: Task deleted successfully
                "404":
                    description: Task not found

4. Add Reusable Schemas

In the components section, define two schemas:

Task

components:
    schemas:
        Task:
            type: object
            properties:
                id:
                    type: string
                    example: "1"
                title:
                    type: string
                    example: Buy groceries
                description:
                    type: string
                    example: Milk, bread, eggs
                dueDate:
                    type: string
                    format: date
                    example: 2026-01-01
                completed:
                    type: boolean
                    default: false
                    example: false
            required: 
                - id
                - title
                - completed

TaskInput

        TaskInput:
            type: object
            properties:
                title:
                    type: string
                    example: Buy groceries
                description:
                    type: string
                    example: Milk, bread, eggs
                dueDate:
                    type: string
                    format: date
                    example: 2026-01-01
                completed:
                    type: boolean
                    default: false
                    example: false
            required:
                - title
                - completed

5. Test Using the API Console

Your API Specification should look like this.

Click API Console to try out each endpoint — no flows required.

You’ll see:

Query parameter validation
404 handling
Schema errors if you send the wrong type
Simulated responses using your example data

This is perfect for quick iteration or mocking out APIs.

6. Publish to Anypoint Exchange

When you're ready to share:

Log into Anypoint Platform via ACB
Press Cmd/Ctrl + Shift + P → "Publish API Project to Exchange"
Choose a business group and version, then publish!

You can now discover and reuse this API inside your org — or scaffold flows from it in the next step.

📦 What’s Next?

In the next tutorial, we’ll take this exact API spec and use it to auto-generate the MuleSoft flows. You’ll implement the endpoints inside VS Code without writing a line of XML manually.

👉 Subscribe to the YouTube playlist for new ACB videos every week.

💡 Pro Tip

If you ever get stuck, I offer Anypoint Code Builder Office Hours to help you troubleshoot and get unblocked.

👉 Book a session here.