API-Led Example: MuleSoft – DZone

This article gives an impression of API-led architecture using Mule4 APIs in order to give a clear understanding of the development process of an API-led approach. It covers all 3 of the API layers (System, Process, and Experience) using Salesforce and FIRST.org as the source. Additionally, we cover applying best practices in each layer of development.

• RAML: Common library,  traits, data definition, reusable resources, health endpoint
• API: Externalize property files, encryption of properties, externalize dwl code, reusable http requester, common error handling, applying policies, applying loggings

Requirements

• Create and get account details from Salesforce CRM
• Input has country code in the request for shipping and billing details tags, which needs to be looked up against FIRST.org open source REST API to get the country name
• Implement clientID enforcement policy with SLA-based rate limiting; limit 100 requests in a minute
• Follow the best practices:
  • Reusable traits, library, and response code in RAML
  • Define respective APIs with proper error handling, global connectors, logging, munit testcases

Common Library

Common Traits

• Client credentials headers: To re-use for APIs where the developer wants to secure the resources using the Client ID enforcement  policy

#%RAML 1.0 Trait
    headers:
      client_id:
        type: string
        description: Client Id for the respective consumer application
      client_secret:
        type: string
        description: Client Secret for the respective consumer application

• Rate limit headers: To re-use for APIs where the rate-limiting policy will be applied

#%RAML 1.0 Trait
usage: Apply rate limiting header to indicate consumer about rate limiting policy

responses:
  201:
    headers:
      X-Ratelimit-Remaining:
        type: number
        description: The amount of available quota
        example: 5
      X-Ratelimit-Limit:
        type: number
        description: The maximum available requests per window
        example: 10
      X-Ratelimit-Reset:
        type: number
        description: The remaining time, in milliseconds, until a new window starts
        example: 3000

Common Health Endpoint

To get the health/heartbeat of an API:

#%RAML 1.0 Library
#This library defines the health resource type
resourceTypes:
  health:
    usage: Use this resource to check health of Mulesoft application
    description: Entity representing a Mulesoft application health
    get:
      description: Get health of an application

Error Response

To define common error codes along with error details:

#%RAML 1.0 DataType
  properties:
    code: 
      type: integer
      required: false
    message:
      type: string
      required: false 

Example:

#%RAML 1.0 NamedExample
code: 400
message: The request could not be understood by the server due to malformed syntax.

Please follow here for the common-lib-1.0.0-fat-raml-fragment code.

accounts-sfdc-sapi

RAML

• Define /accounts to POST the SF account details.
• Define /accounts/{accountId} to perform GET, PUT, and DELETE operations on specific SF accounts.
• Refer common client credentials header for client app validation. EXPERIENCE or PROCESS API will be the client for this API.

#%RAML 1.0
title: SFDC accounts system api
description: API to handle the salesforce account integration
version: 1.0

traits:
  header-client-credentials-required: !include traits/header-client-credentials-required.raml

types:
  address: !include /account/dataTypes/reusable/address.raml
  account: !include /account/dataTypes/reusable/account.raml
  account-request: !include /account/dataTypes/account-request.raml

resourceTypes:
 account: !include /account/resourceType.raml

/accounts:
  type: account
  post:
  /{accountId}:
    type: account
    get:
    put:
    delete:

Please follow here for the accounts-sfdc-sapi RAML code.

API Implementation

Define flows to perform the CRUD operations based on input provided by the process or exp API. The API is secured with the Client ID enforcement policy, so make sure of valid client access.

Please follow here for the accounts-sfdc-sapi code.

first-country-lookup-sapi

API Implementation

Define flow to get the country details from api.first.org. The API is secured with the Client ID enforcement policy.

Please follow here for the first-country-lookup-sapi code.

accounts-papi

RAML

• Define /accounts to post the data received from EXPERIENCE API. Based on the country lookup response from SYSTEM API, post the account details.
• Define /accounts/{accountId} to update the account details received from EXPERIENCE API. Based on country lookup, it will update the account details.
• Refer common client credentials header for client APP validation. EXPERIENCE API will be the client for this API.

#%RAML 1.0
title: Salesforce Accounts Process API
description: API to handle the salesforce account integration
version: 1.0

traits:
  header-client-credentials-required: !include traits/header-client-credentials-required.raml

types:
  address: !include /account/dataTypes/reusable/address.raml
  account: !include /account/dataTypes/reusable/account.raml
  account-request: !include /account/dataTypes/account-request.raml
  account-response: !include /account/dataTypes/account-response.raml

resourceTypes:
 account: !include /account/resourceType.raml

/accounts:
  type: account
  post:
  /{accountId}:
    type: account
    put:

Please follow here for the accounts-papi RAML code.

API Implementation

• Define flow to add new account details received from experience API.
• Define flow to gather country details from system API and pass it to SFDC system API based on details received from experience API.
• API is secured with the Client ID enforcement policy.

Please follow here for the accounts-papi code.

mobile-accounts-eapi

RAML

• Define /accounts to post the SF account details.
• Define /accounts/{accountId} to perform GET, PUT, and DELETEs operations on specific SF accounts.
• Refer common client credentials header for client app validation. The mobile app will be the client for this API.
• Refer common rate limit header to limit the requests from the mobile app.

#%RAML 1.0
title: Mobile Accounts Experience API
mediaType: 
  - application/json
description: API to handle the salesforce account integration along with first org country lookup
version: 1.0
protocols: [ HTTP, HTTPS ]
baseUri: api/{version}

uses:
  commonLib: /exchange_modules/3a821d74-ead4-48a9-87e6-5bb67f180d55/common-lib/1.0.0/libraries/health.raml

traits:
  header-client-credentials-required: !include /exchange_modules/3a821d74-ead4-48a9-87e6-5bb67f180d55/common-lib/1.0.0/traits/header-client-credentials-required.raml
  header-rate-limit-required: !include /exchange_modules/3a821d74-ead4-48a9-87e6-5bb67f180d55/common-lib/1.0.0/traits/header-client-credentials-required.raml
  error-400: !include /exchange_modules/3a821d74-ead4-48a9-87e6-5bb67f180d55/common-lib/1.0.0/traits/errors/json/400.raml
  error-404: !include /exchange_modules/3a821d74-ead4-48a9-87e6-5bb67f180d55/common-lib/1.0.0/traits/errors/json/404.raml
  error-500: !include /exchange_modules/3a821d74-ead4-48a9-87e6-5bb67f180d55/common-lib/1.0.0/traits/errors/json/500.raml

types:
  address: !include /account/dataTypes/reusable/address.raml
  account: !include /account/dataTypes/reusable/account.raml
  account-request: !include /account/dataTypes/account-request.raml
  account-response: !include /account/dataTypes/account-response.raml

resourceTypes:
 account: !include /account/resourceType.raml

/health:
  type:
    commonLib.health

/accounts:
  type: account
  post:
  /{accountId}:
    type: account
    get:
    put:
    delete:

Please follow here for the mobile-accounts-eapi RAML code.

API Implementation

• Define flows to perform operations based on the requests from end clients; i.e., mobile app.
• API is secured with a rate-limiting policy to control the request flows to MuleSoft.

Please follow here for the mobile-accounts-eapi code.

Conclusion

This use case is to give a real-time example of an API-led design and its implementation. I tried to cover all possible best practices of API development. There could be possible improvements on the same.