MuleSoft — Week 1 — Designing APIs

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.

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

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.

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

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.

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
  • POST creates a new resource
  • DELETE deletes a resource
  • PUT replaces a resource completely
  • PATCH partially updates 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.

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.

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.

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

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

DELETE Request

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

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

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.

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

PUT Request

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

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.

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.

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
  • Easy Discoverable
  • Easy to use i.e. making their (developer) lives easier

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

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

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

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

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.

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

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.

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

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

Mocking Service (baseUri)

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

Now you can test by clicking Try It.

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

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.

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

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

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

Make the backup of the root RAML URL.

Set both to visible. Eye icons turn green.

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

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

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.

Configure Access

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

Go to Access Management → Roles → Exchange Administrators

Add yourself.

Configure Exchange

Go to Exchange → Add item → REST API

Name your API American Flights API.

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

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

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

Now, your item is in the Published status.

Go to Week 2

A single golf clap? Or a long standing ovation?

By clapping more or less, you can signal to us which stories really stand out.