MuleSoft — Week 1 — Designing APIs

Chairat Onyaem
Jun 23, 2017 · 10 min read
Image for post
Image for post

I recently registered for online training course Development Fundamentals at MuleSoft.U. Here are my key captures:

Contents

Week 1
API-led Connectivity
SOAP Web Services
RESTful Web Services
Calling RESTful Web Services
Building Successful APIs with MuleSoft
Defining API with RAML
API Portal
Anypoint Exchange

Go to Week 2

API-led Connectivity

The traditional project-based approach is usually built in silo resulting in lacking of reusability and tightly-coupled app.

Image for post
Image for post

To build a new app, you almost have to rebuild everything again with a new project.

Image for post
Image for post

With “API-first” approach, you make all components reusable across enterprise. Components are communicating via standard protocol so you can simply build each component with any platform, any tool you prefer.

Image for post
Image for post

Your components become lego pieces which you can pull them together to build a new app.

Image for post
Image for post

SOAP Web Services

Many years ago, web services was invented with SOAP as the main one of implementation. But it was then not quite popular because its complication of building and usage.

Image for post
Image for post

RESTful Web Services

RESTful Web Services is much simple and easy to use. No XML required like SOAP. It is just working based on simple HTTP protocol.

URI will determines what data or resource you’re working with. HTTP method determines what operation you are performing:

  • GET retrieves the current state of a resource

Go to https://anypoint.mulesoft.com/apiplatform/popular#/portalsGoogle Calendar V3 → API reference, you will see the documentation of the API is and how to use it.

It also shows sample returned data from the service. Normally, JSON (Java Script Object Notation) format is used rather than more complicated XML format.

Image for post
Image for post
Sample returned data from the service (GET)/calendars/{calendar_id}/events/{event_id}

Click “Download API definition as a .zip file” at the bottom of the screen and you will get a RAML file which contain all documentation information about the API.

Calling RESTful Web Services

Here are common HTTP status code returned from the API.

Image for post
Image for post

We will test calling a sample API developed by MuleSoft using Postman. The API URI is http://apdev-american-ws.cloudhub.io/api/flights. This is basically sample flight data and it is publicly accessible.

GET Request

Try to send a GET request and you will get the flight information back in JSON format.

Image for post
Image for post

You can filter the output by putting code=CLE to get the only flights to CLE. The URI is changed to http://apdev-american-ws.cloudhub.io/api/flights?code=CLE

Image for post
Image for post

You can change the URI a bit to get the only flight ID 3. http://apdev-american-ws.cloudhub.io/api/flights/3

Image for post
Image for post

DELETE Request

You can delete the flight ID 3 by sending a DELETE request.

Image for post
Image for post

Please note that you cannot delete all the flight at once. You will get 405 Method Not Allowed.

Image for post
Image for post

POST Request

You can create a new flight by sending a POST request with the following data in the body:

{
"code": "GQ574",
"price": 399,
"departureDate": "2016/12/20",
"origin": "ORD",
"destination": "SFO",
"emptySeats": 200,
"plane": {"type": "Boeing 747", "totalSeats": 400}
}

Don’t forget to change the data format to JSON.

Image for post
Image for post

Please note some attributes are optional, some are mandatory. You can post a new flight without plane attribute but not without emptySeats (Got 400 Bad Request).

Image for post
Image for post

PUT Request

You can send PUT request to replace the whole flight data with the one you send.

Image for post
Image for post

Private API

Try to send a GET request to URI: http://apdev-american-api.cloudhub.io/flights and you will get an error. Because this is a private API i.e. in order to access you need to give your Client ID and Client Secret.

Image for post
Image for post

Try again by giving the Client ID and Client Secret in the URI: http://apdev-american-api.cloudhub.io/flights?client_id=d1374b15c6864c3682ddbed2a247a826&client_secret=4a87fe7e2e43488c927372AEF981F066 and now it is working.

Image for post
Image for post

Building Successful APIs with MuleSoft

Successful APIs are the ones that developers want to use and share with others which normally have these characteristics:

  • Clear purpose on its functionality

MuleSoft provides all-in-one platform to handle the whole life cycle of APIs since designing to maintaining.

Image for post
Image for post

MuleSoft Anypoint platform provides a set of tools that you can work with your API in each of its life cycle.

Image for post
Image for post
Image for post
Image for post
Image for post
Image for post

The Anypoint Exchange is the repository or marketplace for designers (who build APIs) and developers (who use APIs).

Image for post
Image for post

Defining API with RAML

Access Anypoint platform at https://anypoint.mulesoft.com/. You can sign up for 30-day free trial account.

Go to API Manager → Add new API and fill in this information.
API name: American Flights API
Version name: 1.0
Description: API for American flights table in training database

Image for post
Image for post

Click 1.0 link to enter the API Settings of the newly-created API.

Under API Definition, click Define API in API Designer. Here you will start building a RAML (RESTful API Modeling Language) file which is an open standard containing API definition and usage.

We can also generate our API documentation form RAML file and also test it before actually implement it.

Image for post
Image for post

*Anypoint platform currently supports RAML version 0.8

RAML Syntax

RAML is based on YAML and JSON. It is a human-readable data serialization format where data structure hierarchies specified by indentation.

Here is an example of RAML with one resource “flights” which support method GET and POST. We can also GET the flights resource by ID which it can returns 200.

Image for post
Image for post

Go adding this RAML into the API Designer.

#%RAML 0.8
title: American Flights API
version: 1.0
/flights:
get:
queryParameters:
code:
post:

/{ID}:
get:

In API Designer, you will see the screen is split into 3 areas: File Browser, Editor, and API Console.

Image for post
Image for post

After you put the RAML into the editor, the API Console is updated to reflect the RAML immediately. Save the RAML as american.raml.

Image for post
Image for post

You cannot test your API now because you haven’t specified the baseUri.

Image for post
Image for post

Mocking Service (baseUri)

To get the baseUri, turn on the Mocking service and the baseUri will be added automatically.

Image for post
Image for post

Now you can test by clicking Try It.

Image for post
Image for post

You simply click Get to send a GET request. It will returns a message saying that there’s no response specified in the RAML.

Image for post
Image for post

You can additionally test /flights/{ID} resource by specifying an ID and you should get the same result.

RAML Response

To specify RAML response, update the RAML to the following:

#%RAML 0.8
baseUri: (your_mock_url)
title: American Flights API
version: 1.0
/flights:
get:
queryParameters:
code:
responses:
200:
body:
application/json:
example: |
[{"ID":1, "code": "ER38sd","price": 400, "departureDate": "2016/03/20", "origin": "MUA", "destination": "SFO", "emptySeats": 0, "plane": {"type": "Boeing 737", "totalSeats": 150}}, {"ID":2,"code": "ER45if", "price": 345.99, "departureDate": "2016/02/11", "origin": "MUA", "destination": "LAX", "emptySeats": 52, "plane": {"type": "Boeing 777", "totalSeats": 300}}]

post:
body:
application/json:
example: |
{"code": "ER38sd","price": 400, "departureDate": "2016/03/20", "origin": "MUA", "destination": "SFO", "emptySeats": 0, "plane": {"type": "Boeing 737", "totalSeats": 150}}

responses:
201:
body:
application/json:
example: |
{"message": "Flight added (but not really)"}

/{ID}:
get:
responses:
200:
body:
application/json:
example: |
{"ID":1, "code": "ER38sd","price": 400, "departureDate": "2016/03/20", "origin": "MUA", "destination": "SFO", "emptySeats": 0, "plane": {"type": "Boeing 737", "totalSeats": 150}}

Now, we have added example responses to the RAML. Save and test the API again and it should now return with our responses.

API Portal

Now, we have our API defined. Let’s publish it so others can see, play, and provide feedbacks. In this section, we will create the API portal like Google Calendar V3.

In API Settings, under API Portal, drop down and select Create new portal.

Image for post
Image for post

The default portal is created with one Home page and API reference.

Image for post
Image for post

Let’s edit the Home page. Rename it to Overview, click A icon and put the following page content in Markdown format.

The American Flights API is a system API for operations on the **american** table in the *training* database.
####Supported operations####
- Get all flights
- Get a flight with a specific ID
- Add a flight
Image for post
Image for post

Once you click the mouse outside the editor, the markdown will be rendered.

Image for post
Image for post

Make the backup of the root RAML URL.

Image for post
Image for post

Set both to visible. Eye icons turn green.

Image for post
Image for post

Click Live portal icon on the top-right to see preview of our API portal. Make the backup of the URL.

Image for post
Image for post

*Please note the PRIVATE tag indicates this is a private portal which is accessible by only the people in the same organization

Click Themes icon to set the colors and logo.

Image for post
Image for post

Click Private icon to make the portal public which accessible by everyone on the internet. The PRIVATE tag should be removed.

Anypoint Exchange

Anypoint Exchange is a library of connectors, templates, RAMLs, etc. so they are discoverable by your users.

In Anypoint Exchange, you can apply different filters e.g. Scope, Status to search for APIs or resources you want.

Image for post
Image for post

Configure Access

First of all, you need Administrator access to the Exchange.

Go to Access Management → Roles → Exchange Administrators

Image for post
Image for post

Add yourself.

Image for post
Image for post

Configure Exchange

Go to Exchange → Add item → REST API

Image for post
Image for post

Name your API American Flights API.

Image for post
Image for post

Scroll down and click + Add version and input the RAML version, API version, RAML URL and API Portal URL from previous section. Click Done.

Image for post
Image for post

Click Save new item. You item should be appeared in the list with Work in progress status.

Image for post
Image for post

Click the item to open. Click the Publish button and select Master Organization.

Image for post
Image for post

Now, your item is in the Published status.

Image for post
Image for post

Go to Week 2

Chairat.me

Personal blog of a developer who passionate in new…

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app