NYU Developer Support logo

Developer Portal

Knowledge base

Design Best Principles – Documentation

Documentation Best Practices

Section Best Practice Examples
RAML header Include the following elements   

  • title: API title 
  • description: Description of the API
  • mediaType
  • protocol
  • documentation:
    • title
    • content
  • baseUriParameters:
    • description
    • type
#%RAML 1.0
 title: Student API
 description: The Student API is intended to provide basic   operations to access the Students data
 version: v1
 mediaType: application/json
 protocols:
    – HTTPS
 documentation:
    – title: Student domain
      content: |-
         The Student domain contains the following sections:
                – A
                – B
                – C
Resources / Methods Each resource-method pair should include the following elements:

  • description
  • displayName
  /students:
   displayName: /students
   get:
       description: Get all students based on filters
       displayName: get
Responses Each response code should include the following elements:

  • description
responses:
           ‘200‘:
           description: List of student was returned successfully
           body:
               application/json:
                   type: Student
Headers / Query Parameters Each header and query parameter should include the following elements:

  • description
  • type
 headers:
            callerId:
                description: Id to track the request
                type: string
queryParameters:
            filter:
               description: Filter
               type: string
           order:
              description: Order
              type: string
Data Types Each Data Type should include the following elements:

  • description
  • type

Each property should include the following elements

  • description
  • type
Student:
       required: false
       description: Student Data Type
       type: object
       properties:
           id:
               required: true
               description: Student ID
               type: integer
          name:
               required: true
              description: Name of the Student (e.g. John Doe)
              type: string

Exchange – 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

Mule Solution Design – Best Practices

Anti-Patterns

Area  Anti-Patterns  Solution 
Business Logic & Rules  Implementing Business Logic & Rules in Mule expecting features from a BR engine (e.g. rules hot-deployment, testing scenarios, etc) Use dedicated BRMS tools. Get business rules from Mule apps via APIs (e.g. Drools APIs)
Business Process Management Using Mule as a BPM tool  Use BPM for such needs 
 ETL  Using Mule for ETL jobs, and expect ETL traditional features (e.g. staging, monitoring, etc) Though Mule supports ETL processing via Batch components, it’s not an ETL tool with all the traditional features. Use dedicated ETL tools for large volumes of data (> 1 GB) and when specific ETL’s features are needed
Tight Coupling  Developing multiple APIs in a single Mule Project  1 API : 1 Mule app (there are exceptions)

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