Step 2. Design an API Specification

To design an API, assess the purpose and requirements:

  • Identify the type of API: Is it a simple API, part of an integration, or part of a backend system?

  • Understand the data flows: one-way, two-way, or more.

  • Explore the security requirements.

After you define the scope and flow of your integration project, define an API specification in RAML or OAS. Then, in later steps, you’ll use the API specification to quickly develop an API.

API Specifications and APIs

An API is a published interface to a resource that anyone with the correct permissions and a properly structured request can access.

An API specification details the functional and expected behavior of an API, as well as the fundamental design philosophy and supported data types. It contains both documentation and API definitions to create a contract that people and software can read.

MuleSoft provides tools that make it easy to create an API specification that you can then share with your team, your customers, or the general public. Using an API specification increases adoption and shortens project completion time.

Step 2.1: Explore Existing API Specifications

If you look at existing API specifications before writing your own, you can learn how other people have approached situations similar to yours. You can also check whether an API specification with the same objectives is not already in development, and reuse it if appropriate.

Looking for an API specification that already does what you need is easy:

  • Look at the public Exchange, which is a portal hosted by MuleSoft that contains API specifications, connectors, and other assets that you can download and use. You’ll see some of the most popular API specifications, connectors, and other assets displayed on the landing page.

    1. Select All Types > REST APIs (next to the search bar) to display only REST API specifications.

    2. Click on any specification to see the data types and the HTTP requests defined for the API.

  • Look at Exchange for your organization (account). Logging in changes the view to your organization’s private Exchange.

    1. Log in to Anypoint Platform if needed.

    2. In the Anypoint Platform landing page, click Discover and share under Exchange.

    3. Click on any specification to see the data types and the HTTP requests defined for the API. If this is a trial org, you might not see anything yet.

After exploring Exchange to see the range of assets available, return to Anypoint Platform and use web-based tools to create a new API specification that defines what this tutorial API can do.

Step 2.2: Create Your API Specification

Create your own API specification for a simple Hello World API that responds to a simple GET request. To do this, use API Designer, a part of Design Center.

  1. Open API Designer:

  2. Click Create new to open the API Designer editor.

  3. Click New API Spec.

  4. Enter hello-world for API Title and don’t change the other default values.

  5. Click Create API Spec. The API Designer editor displays a sample RAML definition.

  6. Delete the existing text and paste in the following RAML:

#%RAML 1.0
title: hello, world
version: v1
description: A greeting for the world

     todays-greeting: string

               type: greeting
                 {todays-greeting: "test-greeting"}
                 message: string
               example: |
                   "message" : "Greeting not found"

This API specification contains:

  • A single HTTP request, GET

  • A single data type, greeting, with a single property, todays-greeting and a sample value

  • An HTTP success response

  • An HTTP error response

Step 2.3: Test Your API Specification

The API specification hello-world.raml is complete. Now test it by sending a request. The mocking service creates a functioning endpoint from your API specification and provides a simple UI for managing authentication, request headers, and response headers.

To test the API specification:

  1. Open hello-world.raml if it isn’t already open:

    Completed specification

  2. Click the Documentation icon if the Documentation panel isn’t already open.

    API Designer Documentation icon

  3. Look for the label API endpoints. You can see the endpoint you defined. HTTP requests appear in green boxes.

    GET button

  4. Click GET to display the GET request and more information about the specification.

    Response field

  5. Click Code examples to review samples for each protocol.

  6. Click 200 and 404 under Responses to review the responses defined in the API specification.

  7. Click the blue Try it button.

    The Try It button

  8. Click Send to send your request to the temporary request URL that the mocking service creates from your specification.

    Error messages you can ignore

    It’s safe to ignore any error messages on this screen. A successful request returns 200 OK and the test message:

    Results of a successful test

  9. Click Response details in the kebab menu to examine the response headers and request headers in the mocking service to help diagnose issues or understand the behavior of your API specification.

  10. When you have finished testing, open the Mocking Service Configuration panel and click the Select By Default checkmark to disable the mocking service again.

    Mocking service icon

    Mocking service control before being disabled

Step 2.4. Publish Your API Specification

After you have tested your API, publish it to your private Exchange so others in your organization can reuse your work.

  1. Open hello-world.raml if it isn’t already open:

  2. Click Publish.

  3. Click Publish to Exchange.

    User interface for publishing to Exchange

  4. Accept all the default values, and enter a version number in the Asset version field.

  5. Click Publish to Exchange, and then Done.

After publication, anyone in your organization can see the hello-world API specification and reuse it.

What’s Next

Now that you have designed an API and created an API specification for it, use Anypoint Studio (Studio) to create a Mule app that contains the implementation and interface for the API.

Developer Deep Dives

If you’re curious about the details, dive right in.

Deep Dive: Exchange

You can publish assets to the public Exchange, your internal Exchange, or your public developer portal.

  • In addition to the public Exchange, you can review your own organization’s internal offerings.

  • If you’ve created a public developer portal, you can look there as well by clicking Public portal.

Deep Dive: API Features

In a typical API project, you’d likely want to do a few more things:

Developer and Partner Deep-Dive

To share and support your API specification, collect feedback about your API specification for the next version.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub