Module 4: Building APIs

About

The module focuses on building APIs.

Objectives

• Use Anypoint Studio to build, run, and test Mule applications
• Use a connector to connect to databases
• Use the graphical DataWeave editor to transform data
• Create RESTful interfaces for applications from a RAML file
• Connect API interfaces to API implementations
• Synchronize changes to API specifications between Anypoint Studio and Anypoint Platform

Notes

Intro

Mule 4 applications and flows

• Mule applications receive events, process them, and route them to other endpoints

• Mule applications accept and process a Mule event through a series of Mule event processors plugged together in a flow

  

• The flow has three main areas:

  • Source: controls how a flow is triggered
  • Process: determines what it does
  • Error Handling

• A Mule application is a set of XML files which can have multiple flows

• An application can consist of

  • A single flow
  • Multiple flows
  • Multiple flows connected together

• What’s in a typical Mule 4 flow?

  • A Mule event source that initiates the execution of the flow

    • Can be triggered by an event such as

      • A consumer request from a mobile device
      • A change to data in a database
      • The creation of a new customer ID in a SaaS application
  • Mule event processors that transform, filter, enrich, and process the event and its message

Mule 4 event structure

• The attributes contain the metadata or details about the payload

• The payload is the actual data to be processed e.g. payload containing data to create a new resource using HTTP Listener, the attributes will contain the parameters and headers

• Variables are created and managed by processors within the flow

Creating Mule applications with Anypoint Studio

Topic video

• Introducing Anypoint Studio

  

  • Based on Eclipse, a common Java integrated development environment

  • Features include

    • Two-way editing between graphical and XML views
    • Pre-built tooling to connect to APIs (REST, SOAP), protocols (HTTP, FTP, SMTP, more) and popular services (Salesforce, Workday, more!)
    • A data transformation framework and language
    • An embedded Mule runtime to test applications without leaving it
    • Visual debugging
    • Round-trip editing of API specifications with Anypoint Platform
    • One-click deployment of applications to CloudHub
    • Templates for common integration patterns
    • Integration with Maven for continuous build processes

  • Anatomy of a flow: Visual

    

    • Consists of three parts:

      • Event source: can be left empty making it private, so it can only be triggered from withing the application or it may contain a connector for how the flow is trigered from outside the application
      • Event processors: is required and must contain one or more processors to define the operations to perform on a mule event that gets passed through the flow
      • Error handling: is optional and may contain one or more processors to define the operations to perform on the Mule event if an error occurs in the flow

  • Anatomy of a flow: XML

    

    • In the configuration XML view

  • Mule application building blocks

    • Are separated into categories in the Core section of the Mule Palette
    • By default, projects include HTTP and Sockets modules
    • Can add additional modules

  • Running applications

    • Anypoint Studio comes with an embedded Mule runtime to test applications without leaving it
    • The console outputs application logs and information

  • Automating testing of applications

    • You can automate testing of Mule applications using MUnit
    • MUnit is a Mule app testing framework for building automated tests

    • MUnit is fully integrated with Anypoint Studio

      • You can create, design, and run MUNit tests and suites of tests just like you do Mule applications
    • MUnit is covered in Anypoint Platform Development: Production-Ready Development Practices

  • Walkthrough 4-1: Create a Mule application with Anypoint Studio

    • Create a new Mule project with Anypoint Studio
    • Add a connector to receive requests at an endpoint
    • Set the event payload
    • Comment a component
    • Run a Mule application using the embedded Mule runtime
    • Make an HTTP request to the endpoint using ARC

Maven Explained | Lightboard Series

• It comes embedded in Anypoint Studio, and is a build tool

• It helps you build the archive that is used to deploy

• It works around a pom.xml file consisting of various things like project name, dependencies etc

• By default it comes with HTTP and Sockets dependencies pulled from a repository or a set of archives/ artefacts stored somewhere internally or externally

• The artefacts have versions

• When you run Studio, it performs the following tasks:

  • Run Maven to build the archive: resolving all the artefacts, and bring them to an local repository; this is a prerequesite of the mule runtime running properly
  • Fire up the embedded mule runtime

Connecting to data

Topic video

• The Database connector

  • Can connect to almost any JDBC relational database

    • Any database engine for which you have a driver

  • To use

    • Add the Database module to your project
    • Add a database operation to a flow
    • Configure the connection to the database

• Global configuration elements

  • For most operations, a lot of the configuration is encapsulated in a separate global element

    • A reusable configuration that can be used by many operations
    • Defines a connectionto a network resource

  • This is a connector configuration

    • Though it is sometimes referred to simply as the connector

• Walkthrough 4-2: Connect to data (MySQL database)

  • Add a Databse Select operation

  • Configure a Database connector that connects to a MySQL database

    • Or optionally an in-memory Derby database if you do not have access to port 3306
  • Configure the Database Select oepration to use that Database connector
  • Write a query to select data from a table in the database

Database Connectors Explained | Lightboard Series

• First you need to add the dependency to the project

• Then configure which database you’re going to use. This uses the address, and other connection parameters e.g. truststores and keystores for more secure connections

• Then include a driver into the project, JDBC in this instance. It wires the communication, and is critical for Java application communication with the database (Mule sits on top of Java)

• Using Database Select operator

  

  • Needs DB configurations

    • URL
    • Driver (needs to be in the dependency added to the project in pom.xml)
  • The Select operator will call the JDBC driver e.g. MySQL, Oracle etc
  • Translate over the transport protocol
  • Authenticates
  • Runs the Select commands added
  • Returns the data
  • It continues on as part of the mule event structure

• To filter and get a subset of the data,

  • We start off with the query as usual e.g. SELECT * FROM american WHERE col1=:colValue
  • Filter using parameter substitution instead of a fixed value i.e. we can feed in through code
  • The placeholder for substitution begin with a colon
  • Mule provides a place to add the values through DataWeave

  • To create a map or structure to feed to the query

    • Use values { col1Value: vars.myVal } this col1Value is the same one being used in the query

Transforming data

Topic video

• The data return from the database is in Java format, and needs to be transformed to another format using DataWeave

• Transforming data

  • DataWeave 2.0 is the expression language for Mule to access, query and transform Mule 4 event data

  • DataWeave is fully integrated with Studio

    • Graphical interface with payload-aware development
    • In Studio, the Transform Message component is used for transformations

  • DataWeave Playground

    • Interactive browser environment for mocking
    • https://developer.mulesoft.com/learn/dataweave

  • Walkthrough 4-3: Transform data

    • Use the Transform Message component
    • Use the DataWeave visual mapper to change the response to a different JSON structure

Creating RESTful interfaces manually for Mule applications

Topic video

• Creating RESTful interfaces

  • A RESTful interface for an application will have listeners fro each resources / method pairing defined by the API

    • GET: /flights
    • POST: /flights
    • GET: /flights/{ID}
    • DELETE: /flights/{ID{
    • PUT: /flights/{ID}

  • You ca create the interface manually or have it generated from the API definition

    • We will do both in the next two walkthroughs

• Walkhtrough 4-4: Create a RESTful interface for a Mule application

  • Route based on path
  • Use a URI parameter in the path of a new HTTP Listener
  • route based on HTTP method

Generating RESTful interfaces automaticallly using APIkit

Topic video

• Creating RESTful interfaces automatically using APIkit

  • APIkit is an open-source toolkit that includes an Anypoint Studio plugin

  • The Anypoint Studio APIkit plugin can generate an interface automatically from a RAML API definition

    • For new or existing projects
    • Can also work with OAS
  • It generates a main routing flow and flows for each of the API resource/ method pairs
  • You add processors to the resource flows to hook up to your backend logic

• Walkthrough 4-5: Use Anypoint Studio to create a RESTful API interface from a RAML file

  • Add Anypoint Platform credentials to Anypoint Studio
  • Import an API from Exchange into an Anypoint Studio project
  • Use APIkit to generate a RESTful web service interface from an API
  • Test a web service using APIkit console and Advanced REST Client

APIkit Router Explained | Lightboard Series

• The APIkit Router works with API definition to produce some of the application implementation

• It works best to start with a RAML or OpenAPI spec also known as Swagger

• It can be invoked as part of creating a proejct, by providing it from Exchange for example

• The APIkit Router will scaffold some parts of your implementation, which listens for inboud requests

• It will have a main flow with a path of /api/*. This is the entry point into your application.

• It also creates an API console which is documentation listening on /console/*. This is the entry point into your documentation, without having to go to Exchange

• Routing mechanisms happen in the main flow

• There will be corresponding flows generated for each method

• APIkit Router will validate the inbound request, and then call the endpoints based on detecting the path and the method, and also URL, input parameter, and query parameters, headers, body, URI, inputs

• It throws an error if the validation fails. This happens before it routes to the individual requests or routing logic

Connecting interfaces to implementations

Topic video

• Passing messages to other flows

  • Flows can be broken into multiple flows

    • Makes the graphical view more intuitive and the XML code easier to read
    • Promotes code reuse
    • Easier to test with MUnit
  • All flows are identified by name and can be called via Flow Reference components in other flows

  • Studio can list all flow references to a flow or subflow

    • Also provides navigation

• Walkthrough 4-6: Implement a RESTful web service

  • Pass an event from one flow to another
  • Call the backend flows
  • Create new logic for the nested resource call
  • Test the web service using Advanced REST Client

Synchronizing changes to API specifications between Anypoint Studio and Anypoint Platform

Topic video

• Synchronizing API specifications

  • API Sync feature of Anypoint Studio enables you to

    • Pull specifications from Design Center into Studio

      • You already did this
      • You can also initiate the creation of API specifications from scratch in Studio
    • Edit the specification offline in Anypoint Studio
    • Push the updates back to Design Center
    • Publish the new API asset version to Exchange
  • This lets you develop Mule applications while following API lifecycle development practices from within Anypoint Studio

  • If an API specification changes in Exchange, the generated API interface in Anypoint Studio can be update

    • Flows that have already been modified are not overwritten

• Handling change conflicts

  • The APi Design perspective includes a Git Staging tab
  • Under the hood, Git version control system is used to pull, push, and merge branches made to API specifications

  • If someone modifies the version in Design Center while you are modifying the same version locally, a conflict is triggered in Git

    • You must tell Git how to apply your changes over a modified version

• Walkthrough 4-7: Synchronise changes to an API specification between Studio and Anypoint Platform

  • Create an editable version of an API specification in Anypoint Studio
  • Make changes to an API specification in Anypoint Studio
  • Push the changes from Anypoint Studio to Design Center
  • Publish the modified API specification from Studio to Exchange
  • Update the version of an API specification used in a Mule project
  • Rescaffold an API interface from an updated API specification

Summary

Anypoint Studio can be used to build Mule applications for integrations and API implementations

• Two-way editing between graphical and XML views

• An embedded Mule runtime for testing applications

Mule applications accept and process events through a series of event processors plugged together in a flow

• Use the HTTP Listener as an inbound endpoint to trigger a flow with an HTTP request

• Use the Set Payload transformer to set the payload

• Use the Database connector to connect to JDBC databases

• Use DataWeave and the Transform Message component to transform messages from one data type and structure to another

• Create RESTful interfaces for applications

  • Manually by creating flows with listeners for each resource/ method pairing
  • Automatically using Anypoint Studio and APIkit

• Connect web service interfaces to implementations using the Flow Reference component to pass messages to other flows

• Synchronize changes to API specifications between Anypoint Studio and Anypoint Platform using API Sync

Test your knowledge

Checkout

Apply your knowledge: DIY #1

Apply your knowledge: DIY #2

Creating Mule applications with Anypoint Studio

Topic video

Walkthrough steps

Extras

Anki

Links

• Anypoint Platform Development: Fundamentals - Notes - Part 1: Getting started with Anypoint Platform
• Module 3: Designing APIs
• Module 5: Deploying and managing APIs

References