Step 2. Design an API Specification | MuleSoft Documentation
# 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 **Any Type > REST APIs** 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.
Take me to Anypoint Platform
    1. Log in to Anypoint Platform if needed.
    2. In the Anypoint Platform landing page, go to the **Exchange** section and click **Discover and share**.
    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.
## Step 2.2: Create Your API Specification
Create your own API specification for a simple Hello World API that responds to a GET request. To do this, use API Designer, a part of Design Center.
  1. Open API Designer:
  2. Select **Create > New API Specification** to open the API Designer editor.
  3. In the **New API specification** dialog, enter `hello-world-api` in **Project Name** , don’t change the other default values, and then click **Create API**.
The API Designer editor displays a sample RAML definition.
  4. Delete the existing text and paste in the following RAML:


```
#%RAML 1.0
title: hello world
version: v1
description: A greeting for the world
types:
 greeting:
  properties:
   todays-greeting: string
/greeting:
   get:
    responses:
     200:
      body:
       application/json:
        type: greeting
        example:
         {todays-greeting: "test-greeting"}
     404:
      body:
       application/json:
        properties:
         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
Now test your `hello-world-api` API specification by sending a request using the mocking service. 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-api.raml` if it isn’t already open:
  2. Click the Documentation icon if the Documentation panel isn’t already open.
  3. Look for the label **API endpoints**. You can see the endpoint you defined. HTTP requests appear in green boxes.
  4. Click **GET** to display the GET request and more information about the specification.
  5. Click **Show** to review code examples for each protocol.
  6. Click the **200** and **404** tabs to review the responses defined in the API specification.
  7. Click the **Try it** button:
  8. Click **Send** to send your request to the temporary request URL that the mocking service creates from your specification.
It’s safe to ignore any error messages on this screen. A successful request returns `200 OK` and the test message:
  9. Select **Response details** in the more (…​) 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 finish testing, open the **Mocking Service Configuration** panel.
  11. In **Local Settings** , enable **Select By Default**.


## Step 2.4. Publish Your API Specification
After testing your API, publish it to your private Exchange so others in your organization can reuse your work.
  1. Open `hello-world-api.raml` if it isn’t already open:
  2. Click **Publish**.
  3. In the **Publishing to Exchange** dialog, accept the defaults and click **Publish to Exchange** :
  4. Click **Close** in the confirmation dialog.


After publication, anyone in your organization can see the `hello-world-api` 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:
  * Add authentication.
  * Add annotations as defined in the RAML specification.
Take me to the RAML specification
  * Add assets from Exchange using API Designer or Studio.
  * Model the data your API specification exposes, using Studio.
  * Modularize your specifications for reuse with API fragments.


### Developer and Partner Deep-Dive
To share and support your API specification, collect feedback about your API specification for the next version.