Designing your first API

designing your first api
MuleSoft Staff
20 min read

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.
  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: 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

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.

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):
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. At the top of the Get window, click the blue Try It button. This takes you to the Authorization, Parameters and Headers menu.
  4. To test the request, go to the Parameters submenu and enter 2 in the productID* field.
  5. In the Authorization menu, insert the following credentials in the modal:
    • username: mulesoft
    • password: mulesoft
  6. Click Authorize and Send
  7. Verify that 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 ›

Try Anypoint Platform for free

Start free trial

Already have an account? Sign in.

Related tutorials