Support

RAML Best Practices

General

• Title and documentation must be defined.
• RAML file name must be different from api.raml
• User RAML version 1.0
  • https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/
• Base URL & Versioning
  • Include the “api” word and the version of the API in the base Url (e.g. domain/api/v1)
• Fields
  • Use lower camelCase, preferable not underscores (e.g.: lastName)
  • Use snake_case (e.g: last_name)
• Define a transaction_id/caller_id header to track the requests (optional)
• Date Time Representations
  • Use UTC
    • ISO8601
  • Use standard date formats
    • 2018-01-02T13:42:21+00:00 (+00:00 is the time zones hour offset)
    • 2018-01-02T13:42:21Z     (Z is place holder for local time zone)

Methods

• GET, POST, PUT, DELETE
• Should be used following the right verb logic
  • GET: For obtaining data.
  • PUT (Idempotent): To update data. It will update the entire instance.
  • PATCH: To update data. It will update partial data of an instance.
  • POST (Not idempotent): To store data.
  • DELETE: To delete an instance.

Version

• Has to be defined (v1,1.0) for the resources.

Resources

• Under each resource, all fields should be written using lower camelCase
• Resources
  • Use nouns, not verbs, lower case. Example: /users, /accounts
  • Coarse grained, not fine grained
  • For resources with more than 2 words
    • use lowercase for both words (example: /lineitems) or
    • use kebab-case (aka spinal-case) (example: /line-items)
• Error codes defined in each resource-method pair

Query Parameters

• Use snake_case (example: date_from, date_to)
• When dealing with collections, use comma separated values, e.g. /users?fields=name,last_name

Media Types

• For the request: use ‘Accept’ header
• For the response: use ‘Content-Type’

Resource Types

• Collection resource
  • /users
• Instance resource
  • /users/{id}  (example: /users/123 )

Schemas, Data Types

• Separate the schemas and data types from the base RAML file. Externalize them in a separate file.
• Should contains valid – mocked data

Examples

• Always include examples
• Separate the examples from the base RAML file. Externalize them in a separate file.
• Should contains valid – mocked data

Traits

• Use traits to define common method properties such as query-parameters and responses.
• Separate the traits from the base RAML file. Externalize them in a separate file.

Security

• Security traits defined
• Confidential data should be obfuscated / avoided in examples, query parameters, etc.

Discoverability

• API Fragments
  • Common data types, traits, resource types, schemas, examples, must be externalized as API Fragments in Exchange to promote reusability in API Design.
• Schemas/Examples/DataTypes defined for each resource

Response Codes

HTTP status codes are grouped into five numeric categories:

These response codes should be used as standard, the use of not defined return codes is discouraged and should only be done in exceptional circumstances. 

Documentation Best Practices

Portal Content

API Fragments Portal

• Description must be completed
  • Not extensive
  • Concise
  • Clear and useful
• Use case
  • Always add a use case showing the usage of the asset

APIs Specification Portal

• Portal Content

  • Description must be completed, not extensive, concise, clear and useful
  • Include a How-To (preferable a short video/gif showing how to request API access and how the Portal works)
  • Include authentication / authorization requirements details for accessing the API (e.g. client ID & client secret, OAuth 2.0)

• API Console

  • Make sure it is accessible
  • It should work for each resource and method
  • Include Mocking Service instance

• API Notebook

  • Optional
  • Include if your API is a part of a process workflow and there is a need to show the usage

Mule Solution Design – Best Practices

Anti-Patterns

Synchronous Patterns

• API (RESTful services) developed using RAML for all synchronous communication 
• API proxy used to proxy existing web services (SOAP/REST) 
• Use a Message Broker/VM for Async needs inside synchronous scenarios 

Asynchronous Patterns

• Mule support Asynchronous patterns via “Async” component,  Virtual Machine (VM) and Java Message Service (JMS) connectors 
• VM component can be used to convert non transactional components like http, ftp, tcp into transaction component which helps in rolling back transactions, retry mechanisms etc. 

• Asynchronous message handling is one of the keys to use Mule effectively. Mule support Asynchronous processing patterns in many different ways like 

• • Setting exchange-pattern of a message source to “one-way” enables asynchronous processing for a flow 
  • Asynchronous processing for a flow can be tuned by defining a queued-asynchronous-processing-strategy. Multiple queued-asynchronous-processing-strategy can be defined and set using the flow’s “processingStrategy” attributes 

Publish/Subscribe Patterns

• A Message Broker (AnypointMQ, ActiveMQ, Kafka, RabbitMQ, WMQ, etc) should be used for Asynchronous integrations to implement pub-sub model 

• Create topics based on application needs, topics can be classified by application, message types etc. 

File Handling

• File handling should always ensure zero file/message loss and should include a reprocessing strategy or backup in case of error files 
• Do not delete or overwrite input/output files  

• Be careful when using the autoDelete and the moveToDirectory attributes of the File Transport
• If streaming is enabled for each file that is processed, make sure that the stream is properly close after reading 
• Always ensure that the file/ message has been archived correctly once entered in the mule application / flow 
• Don’t save file contents / complete file / payload in session unless it’s required 

• Define correct file handling strategies, considering all the failure / success / transaction / unhandled error scenarios 
• Ensure that the directories used in the file handling have correct read / write permissions
• When a file reading process is scheduled, ensure that the same file is not picked up for processing when the next schedule starts. 
• Create directories like “working”, “error”, “processed” directories to manage files. For example, when a file is selected for processing, move it to the “working” directory, on successful processing move it to  the “processed” directory, if the process fails, move it to the “error” directory 

Large Data Handling

• Mule has out of the box  Batch Processing components that can be used for Data synchronization between systems for large data
  • Reference: https://docs.mulesoft.com/mule-user-guide/v/3.9/batch-processing 
• Data could be considered large in Mule if it’s > 20 MB (per request/transaction).  It  also depends on worker size, complexity of implementation, etc. 

• Dataweave, Streaming, etc can be used appropriately based on the use-case 

Error Handling

Consider the following categories of errors when designing Mule flows:

• Business Logic errors: Thrown by validations and conditions based on the use case requirements.
• Systems’ availability errors: Errors based on the source/target systems’ availability and re-connection strategies (Connection timeout, max retries reached, etc) 

In any of the previous cases don’t expose the exception message or the stack trace, instead, include descriptive messages mapped to internal error codes.

Don’t include error handling for the following categories:

• Development errors: To cover bad development practices, like bad parsing, bad transformation inputs, etc.