We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. You can read more and make your cookie choices here. By continuing to use this site you are giving us your consent to do this.


Quick Start

Designing your first API

Welcome to the MuleSoft Quick Start guides. This is a 4-part guide that helps you navigate different areas of the platform while going through the API lifecycle. Here is what you will learn in each guide:

Guide #What you will do
1 - Designing your first API (this guide)Build an API Specification using Anypoint Design Center and publish it onto Anypoint Exchange for consumption
2 - Developing your first Mule applicationDevelop a Mule application that gets data from a MySQL Database using Anypoint Studio
3 - Deploying and managing your first APIDeploy your local app on Cloudhub infrastructure and apply policies to it
4 - Connecting your first SaaS applicationsRe-use your API to integrate with Salesforce and Slack using Flow Designer

Solutions to each of the guides are published on Anypoint Exchange. If you simply want learn about how to deploy an API that is already designed and built, skip to Guide 3. The Get Set up section with help you download and import the solution file.


    In this guide, you'll learn about API specifications and how MuleSoft's Anypoint Platform leverages them to begin building a data integration, mainly:

    • What is API Designer and how to create an API spec using it?
    • What are some time-saving considerations to make when designing an API specification?
    • How do you test/validate against your API specification in API Console?

    Why design an API spec first

    The best way to get started in building your first HTTP-based Mule data integration application is by writing an API specification. Taking the time to create a specification offers several key benefits:

    • Serves as documentation for the consumption and reuse of the deployed API by future applications via Exchange.
    • Stakeholders/consumers of the APIs can perform acceptance tests before the app is ever built.
    • The API specification can be used to pre-populate your implementation with artifacts and metadata to reduce development time.

    Get set up

    1. Make sure you sign up for a free 30-day Anypoint Platform account if you haven’t done so yet. You'll need to use it to create your API specification in API Designer and Mule Apps in flow designer.
    2. Download the Excel representation of the product's database; you'll be using it in the next exercise to serve as a reference when building your API:
      File congo.xlsx

    What is an API specification

    An API specification is a powerful contract that is easily digestible by both humans and computer systems. It's digestible because it combines both API documentation (e.g. readme's) and API definitions (e.g. WSDL files). This design simplifies understanding how to interact with the implementation, which increases adoption and speeds up project completion. So let's start thinking about our API specification in the language you'll be using: RAML.

    RAML is the native API specification language in MuleSoft's API Designer, though OAS/Swagger import is also supported and converted to RAML. For more information on RAML, please visit RAML.org.

    Leverage an eCommerce example

    Assume you're building APIs for an eCommerce store, you can begin by building a product API. One of the requirements for a product API is to provide details about a specific item in the store. You can create a /products/{productId} endpoint that supports a HTTP GET method and provide details on what to request and respond.

    Creating an API spec in Design Center

    Let's start by going into Design Center in Anypoint Platform:

    1. Select the Create button → API Specification.
    2. Fill out the modal's text field with a name for your API specification.
    3. Select "Start with API Designer."
    4. Press Create.

    Create a new API specification

    This will load a new API Specification window in API Designer allowing you to create your API specification:

    1. Delete the default text in the textbox so it's empty.
    2. Copy and paste the RAML below into a blank API Designer textbox (Alternatively, you can also download the RAML directly from the public Exchange – this is how you might save time in a real-world scenario where another team has defined the API already):
    #%RAML 1.0
    title: DevRel-Quick Start Products API
    version: v1.0
        description: |
          This API supports Basic Authentication.
        type: Basic Authentication
    securedBy: [basic]
          identifier?: string
          identifiers: IdentifierMap
          brand: string
          model: string
          rating: number
          description?: string
          pictures: string[]
          price: price
          amount: amount
          salesUnit: salesUnit
          currency: string
          currencyValue: number
          name : string
          code: string
          name: string
        type: string
        pattern: ^[0-9A-Za-z-]+
        minLength: 3
        maxLength: 36
        type: array
          type: object
              type: Identifier
            productId: string
                    type: product
                    example: |
                        "brand": "Anypoint",
                        "identifier": "eb8c8ca7-3c42-4489-a820-3aa138430b75",
                        "identifiers": [{
                          "SKU": "UGG-BB-PUR-06"
                        "model": "Smart Slim Micro Stripe Shirt",
                        "rating": 5,
                        "description": "Shirt by ASOS Tall. Stripe woven fabric. Added stretch for comfort. Spread collar. Button placket. Slim fit - cut close to the body. Machine wash. 98% Cotton, 2% Elastane. Our model wears a size Medium Long and is 193cm/6'4\" tall",
                        "pictures": [
                        "price": {
                          "amount": {
                            "currency": "USD",
                            "currencyValue": 34.90,
                            "name": "Amount"
                            "salesUnit": {
                            "code": "EA",
                            "name": "Each"
                      message: string
                    example: |
                        "message" : "Product not found"

    Understanding the specification

    Take a look at the specification above, which starts by describing the overall API from the top-level.

    It then defines the authentication methods supported (basic auth) and then assigns that globally for all endpoints and methods with the securedBy parameter.

    The specification creates a data-type of product with its parameters and types within it. Below that, you can find data-types such as identifiersMap, price, sales unit, and more. By specifying these data-types, they can be reused by referencing them throughout the RAML file.

    Scrolling further, the spec describes the endpoint (/products/{productId}) and what it expects from the requester—the item ID, content-type, and enumerated query parameters—as well as it's responses. A successful 200 outputs the data types specified for the JSON body, along with an example of the 200 response. At the very end, there's also one exception error with a status code of 404 Not Found.

    Test the API with mocking service

    It's now time for you to test the API specification to prototype the API implementation. First, turn on the built-in mocking service in API Designer by flipping the switch in the right-hand pane.

    Start API mocking service

    At the top of the RAML spec, there's a new parameter called baseUri—this public URL is the base path to accessing the API, all endpoints are appended to this base path.

    The mocking service is only meant for testing and not for production use.

    Send a request to mocking service

    The right-hand pane also includes the API console to try a request and see the response against the specification.

    1. Hover the mouse over to the right-hand pane.
    2. Click the /{productId} to view the endpoint details.
    3. Scroll to the bottom and click GET for the /products/{productId} endpoint.
    4. Click the blue Try it button.
    5. Enter an ID into the productId text field (e.g. 2).
    6. Click Send.
    7. Insert the following credentials (or any) in the modal that pops up.
      • username: mulesoft
      • password: mulesoft
    8. Verify that the the mocking service's response is loaded below.

    The mocking service should return a 200 response with the example body. This can be tested by performing a similar request by using another Web client such as curl or a web browser.

    curl -X GET https://{{yourMockingServiceUrl}}/products/1

    The mocking service URL can be shared with other stakeholders and should be tested against during the design phase.

    Publishing the spec for reuse

    Now that the specification works without errors, let's go ahead and publish it. This enables you and anyone with sufficient privileges in Anypoint Exchange to read and use it. But first, you need to shut off the mocking service to remove the BaseUri parameter.

    Stop mocking service

    Finally, to publish your finalized API specification, simply:

    1. Click the Publish icon in API Designer.
    2. Select Publish to Exchange.
    3. Leave all the default values.
    4. Click Publish.

    Publish API to Anypoint Exchange

    The blueprint of the application that you will build is now available to a larger audience, which can then build off of it or reference it later in the future. 

    Now that the API spec has been published, you can see it on your private Exchange by searching for "Quickstart-store" (or whatever name you chose in the earlier step for your project). You can verify that your API spec is correct by comparing it against the one we've already published on the Public Exchange.

    Next Steps

    You did it! You built, shared, and tested your API specification in Anypoint Platform! The next thing to do is to build and deploy a Mule application, using this API spec you just created to pre-populate your application with endpoints and flows.

    Go to: Developing your first Mule application ›