Build your first API Specification with API Designer

build-first-api-specification
aridam-kumar-headshot
Aridam Kumar
Technical Product Marketing Manager
10 min read
Getting started

Is this your first time developing with MuleSoft? If so, please read our Hello Mule tutorial to learn how to build your first API/application in Anypoint Studio and deploy it to CloudHub.

Read Hello Mule tutorial

Many developers have experience consuming APIs in their daily development work but have never designed a REST API from the ground up. If you have ever wanted to learn how to develop an API, this tutorial will walk you through how easy it is to create your own, fully functional API with MuleSoft’s Anypoint Platform. Even with no API Design experience, this tutorial will teach you how to publish your first API Specification (also known as an API Contract) in around 5 minutes! This is part one of a four-part quick start tutorial series that will instruct you on the best practices to build a production-ready, scalable API and integration.

The first step in the API development process is to brainstorm how we want our API to operate. Do we want our API to return a 200 valid response on POST requests and return a 405 method not allowed on GET requests? Do we want to design a RESTful API or a SOAP API? Do we want our API to be HTTP, HTTPS or both? What data types do we want to accept in our API request? All of these questions are parameters that we can set while building our API within MuleSoft’s API Designer.

The problem

Danny works for Northern Trail Outfitters (NTO), a retailer of sports apparel, gear, and nutrition products. NTO has an old customer database that requires special drivers and permissions to access. Danny wants to make this data widely and easily accessible across NTO. To make this possible, he decides to build a REST API on top of the database.

NTO-database-API-connection-diagram

To start, Danny must first design the API and document it in an API specification. Next, Danny can build the implementation (logic and connectivity) of the API. MuleSoft’s Anypoint platform can support Danny’s end to end process, providing both design and implementation tools.

What is an API?

An API is a type of technology that allows applications to talk to one another. APIs provide an easy and consistent way for developers to access data from backend systems, which helps secure the system and reduces complexity for developers that simply need some information from the backend system rather than the entire logic and database. The client sends a request for specific information or functionality to another system. That system returns the data or functionality in a response. For example, when visiting a restaurant, customers do not go into the kitchen to get the food that they want. Instead, they place an order with a waiter who then goes into the kitchen and retrieves the items. APIs are the equivalent of the waiter, serving the information that a user requested.

What is an API Specification?

To send or receive data using an API, there is an expectation that it will be in a specific format that both sides can understand. That format is often very sensitive to the context(s) it serves. For example, when using an electrical appliance, the user knows that all wall sockets have a certain shape and provide electricity at 120 volts. These known guidelines essentially set an expectation for any device needing to be plugged into the wall. API specifications, written in the RESTful API Modeling Language (RAML) or Open API Specification (OAS) formats, provide the specific guidelines by which the API is built and communicates, just like an assembly guide and user manual. Specifications can include the following components:

  1. API basics: Initially, the specification must clearly state the title of the API and the industry standard that it will follow. Although there are many different options available here, this tutorial will be building a REST API. You must also specify a base URI which is the URL that your API is hosted at, but this can be added later once the API is deployed to a hosting service. You can also choose to specify the communication protocol, such as HTTP, that your API will support.

  2. Security: This section defines the method(s) used to secure the data that the API is making accessible. Every request made to the API must satisfy at least one of the authentication methods that the API was built to support. You can learn more about authentication types here.

  3. Resources: This section defines the various resources available from the API (such as customer information, order information, etc). In the case of REST APIs, these resources can be accessed using resource methods to retrieve (GET), write (POST), update (PATCH or PUT), and remove (DELETE) information. Each resource has its own URL and can have specific security policies.

  4. Responses: Once an API request is made, the API must know exactly how to respond. The HTTP communication standard defines status codes that indicate the type of response, such as a successful GET request (200), or a “method not allowed” error (405). There are many response types, and you can learn more about them here. This section will define each status code the API can return, along with the different types of data returned.

  5. Data Types: Each resource method can have its own set of request and response parameters that the user must work with. Each parameter can be of a different data type, such as “string”, “integer”, “array” etc. The data types are defined in this section and can be used for both requests and responses.

With so many things to consider when developing a good API, a simple platform that guides a user through the API design process can really make life easier! That is where MuleSoft’s Anypoint API Designer comes in. Let’s take a closer look at how Danny can use the API Designer to build and publish a simple API for NTO’s customer database.

Create the API Specification
Step 1: Access API Designer - sign up for free!

Let’s help Danny build his API so that he can retrieve contacts from the database. To get started, click the button below to create a free MuleSoft Anypoint Platform account. Once you are logged in to Anypoint Platform, navigate to the Design Center.

Step 2: Create the API Specification

Click the Create button, and select Create API Specification. You will see a pop-up like the one shown below.

new-API-spec-setup

Here you have a few different options that you can use to setup the specification. First, you must give your API a title, and in this example we will use “NTO Customer Database API”.

Now you can select whether you would like to use an API specification language to build your specification, or the guided visual editor that will scaffold the API for you. The editor currently supports OAS and RAML, but for the purpose of this tutorial we will use the visual editor which will develop both specifications for you in realtime. Go ahead and select “Guide me through it” and continue to Create API Spec.

Build the API Specification in API Designer
Step 3: Define the specification summary and data types.

Now that you have entered the API Designer, you will see the modules dedicated to the various specification components we discussed earlier.

The first page you land on is the API Summary module, which is where you can configure the API Title, the communication methods (protocol and media type), the base URI, and provide a description. At this point you can manually configure your API per the instructions below, or you can import an existing API specification from Exchange (we will publish this specification to Exchange so you can import it in the future). We will use the following details:

Title: NTO Customer Database API
Version: 1.0.0
Protocols: HTTP & HTTPS
Media type: application/json
Base URI: api.samplebaseuri.com
Description: A simple API to retrieve information from Northern Trail Outfitters’ customer database.

NTO-customer-database-API-summary

Along the right, you will notice that RAML and OAS code is automatically generated as you update the specification in the visual editor.

API-RAML-diagramAPI-OAS-diagram

Along the left pane, you will see options to configure security schemes, resources, and data types. Let’s add some of the data types and resources that your API will need.

API-designer-left-navigation

Select the “+” icon next to the data types tab on the left, and configure the following:

  1. Data type 1:
    • Name: address
    • Type: object
    • Description: Address data type
    • Properties:
      • “street” - string
      • “city” - string
      • “postalCode” - string
      • “state” - string
      • “country” - string
    • Example:
       

      {
      "street": "44 Shirley Ave.",
      "city": "West Chicago",
      "postalCode": "60185",
      "state": "IL",
      "country": "USA"
      }

address-data-type
  1. Data type 2:
    • Name: contact
    • Type: object
    • Description: Contact data type
    • Properties:
      • "firstName" - string
      • "lastName" - string - required
      • "phone" - string
      • "email": string
      • "deliveryAddress" - address
      • "postalAddress" - address
    • Example:

      {
      "firstName": "Danny",
      "lastName": "Brookshire",
      "phone": "123-412-3412",
      "email": "danny.brookshire@example.com",
      "deliveryAddress": {
      "street": "44 Shirley Ave.",
      "city": "West Chicago",
      "postalCode": "60185",
      "state": "IL",
      "country": "USA"
      },
      "postalAddress": {
      "street": "44 Shirley Ave.",
      "city": "West Chicago",
      "postalCode": "60185",
      "state": "IL",
      "country": "USA"
      }
      }

contact-data-type
Step 4: Define the specification resources.

Next, select the “+” icon next to the resources tab on the left. Configure 2 resources as follows:

/customers:

  • Resource path: /customers
  • Resource method: GET
  • Name: Get list of customers
customer-resource-setup

Configure the response for the /customers resource:

  1. Select the “Responses” tab and “Add New Response”.
  2. Ensure that the status code is “200 OK” and then click “Add Body”.
  3. Ensure that the media type contains “application/json” and set the type to “Array”
  4. Expand the body from the arrow at the right, and add a property called “customers”, set to the “contact” data type that you just created.
customer-resource-responses-setup

/customers/{customerId}:

  • Resource path: /customers/{customerId}
  • Resource method: GET
  • Add a URI parameter: customerId (required)
  • Name: Get customer by ID
customer-id-resource-setup

Configure the response for the /customers/{customerId} resource:

  1. Select the “Responses” tab and “Add New Response”.
  2. Ensure that the status code is “200 OK” and then click “Add Body”
  3. Ensure that the media type contains “application/json” and set the type to the “contact” data type (note that this response contains a single customer rather than an array of customers as Resource 1 has)
customer-id-responses-setup

Congratulations! You have now successfully helped Danny by building a specification for two GET endpoints for NTO’s customer API. The first “/customers” endpoint will return an array of contact objects for all customers, and the second “/customers/{customerId}” endpoint will return a single contact object for the customerId provided in the request URL.

Test and Publish the API Specification
Step 5: Testing your API using the Mocking Service

Now it is time to test the API. The API Designer offers a mocking service, which enables you to simulate the behavior of an API specification. The mocking service provides a test link to an API and returns the responses (both HTTP status codes and example payloads) that are defined in your API specification.

By default, the mocking service is limited to users within your Anypoint account. You can also enable a public link that can be shared with users outside of Anypoint Platform, which is useful when collaborating with other team members or customers and soliciting feedback.

If you specified a base URI, API Designer enables you to use either the base URI or the mocking service when simulating an API call. API Designer does not make any changes to your APIs.

Let’s use the mocking service to test the API:

  1. Navigate to the “/customers” resource in the left navigation pane.
  2. At the far right of your screen you will see a few icons, and hovering over them will indicate what each does. Select the one that indicates “Try It”, which will take you to the API testing panel.
  3. Under “Select Server” choose the “Mocking Service”. This creates a dummy API request and displays the example response as it would appear if the API was live and returning data.
  4. Press “Send” to view the example response.
mocking-service-panel
  1. Repeat steps 1-4 for the “/customers/{customerId}" resource to see a similar response for a single customer.
  2. If you wish to create a public link that you can share with other users for testing purposes, you can do so from the “Mocking Service Configuration” tab at the right.
mocking-service-configuration
Step 6: Publishing the API to Exchange

Now that you have put all this effort into building the API for NTO, we want to ensure that Danny and his other team members can take advantage of your work by reusing this API specification rather than always reinventing the wheel. Let’s publish the API to Exchange so other users can download and work with it:

  1. Select the “Publish” drop down from the blue button at the top right, and then select “Publish to Exchange”.

  2. In the new window, enter an asset version number that will help you and others identify the version of this particular publication (separate from the API version). You will notice that the API version is inherited from the root file which we just configured using the visual editor. Note that API Designer and Anypoint Exchange are closely linked together to make API and asset versioning easier. Over time, you can make changes to the API specification and update the asset version without affecting the API version, or you can update API functionality and release a new version altogether. Click here to learn more about API and asset versioning on Exchange, including best practices.
publish-to-exchange-setup
  1. Select “Publish to Exchange”, and you’re done! Users can now visit Exchange from the Anypoint Platform homepage to view your API specification as shown below, and it can be imported via Exchange into Anypoint Studio to continue development and connect the customer database with other cloud applications.
nto-customer-api-on-anypoint-exchange
And that’s it! Let’s recap:

Mulesoft Anypoint Platform’s Design Center provides a seamless, integrated way to design and develop APIs. The API Designer guides users through the API specification writing process, where users can either write RAML/OAS, or use a visual editor that builds the RAML/OAS specification automatically. Once the API specification has been built, it can be tested using the API Mocking Service, and can be published to Anypoint Exchange to be shared with other developers.

Congratulations on building and deploying your first API using MuleSoft's Anypoint Platform. Thanks for reading, your feedback is much appreciated. Please rate this tutorial below.

Try Anypoint Platform for free

Start free trial

Already have an account? Sign in.

Related tutorials