WSO2 ESB Development best practices

Naming Conventions

When developing artifacts for WSO2 servers, follow the guidelines mentioned below.

1. Project names - Create project names which reflects the intention of the project. It is better to end the project name with the server type which this project is deployed in to. This name should be unique within your source code repository

2. Artifact names - When you create artifacts, always better to start the name with the project name and end with the artifact type. This would make the artifact name unique within the source repository.

3. Custom Java Classes - When you create custom java code (custom mediators, custom formatters), adhere to the standard java packaging names with project names to distinguish your code

Project Structures

When developing artifacts for WSO2 servers, follow the guidelines mentioned below

1. Start with a “Maven multi module” project as your parent project. This will be the top most level project in your source code hierarchy.

2. Create projects according to the artifact types which you are going to develop.

Ex: ESBConfigProject to develop ESB artifacts, RegistryResourceProject for governance artifacts

3. Create Composite ARchive (CAR) projects to bundle the relevant artifacts into an archive.

4. If you need to create a common (core) project to include different types of projects (ESB, Registry), create a maven multi module project and add them as sub projects.

5. Do not bundle custom mediators with the ESB artifacts which referenced that specific mediators in a single CAR file. This may cause deployment time exceptions during the due to dependencies conflicts. If you have a custom java code, always deploy that before deploying the ESB artifacts, which refers this custom code

General Best Practices

When you have environment specific artifacts such as endpoints, data source configurations, always better to use governance registry to store them.

When sharing the implemented projects among team members of the development team, use WSO2 Project Import Wizard since WSO2 Project Import Wizard is knowledgeable on handling the nested project structures supported by Developer Studio.

When exporting Developer Studio Projects you can either export individual projects and generate individual deployable artifacts or you can package them into a CAR file and export thar CAR file from IDE itself.

If you need to integrate your solution with a Continuous Integration server(Ex:Bamboo, Jenkins) and automate the build and deploy process, you need to use Maven support provided by Developer Studio for that. You should not include the Carbon Server extensions in CAR files and deploy to Carbon Servers,

Developer Studio - Deployment Best Practices

When you want to deploy artifacts to a Carbon Server, first you need to package all the artifacts to a CAR file. There are 2 possible methods to deploy to a Carbon Server.

Via Developer Studio IDE

Via Maven-Car-Deploy-Plugin

You can use any of the above 2 methods to deploy the CAR files to a Carbon Server. When you have modified your projects in Developer Studio, you can simply use Maven or IDE to publish latest version of the CAR file to the Carbon Server.

Design and Development Best Practices

1. Use mediators like XSLT and XQuery in complex transformation. Payload Factory and Enrich mediator perform better in simple transformation scenarios.

2. When a message is sent out from the inSequence , the reply is received by the outSequence by default. To receive the reply to a named sequence, use send mediator in the inSequence .

3. Do not use two consecutive send mediators without cloning the message using Clone mediator.

4. Always use REST APIs to expose RESTful interfaces over invoking Proxy Services.

5. Aggregation mediator works in tandem with Iterate or Clone.

6. Use templates to reuse the ESB configuration whenever possible.

7. Limit the use of in-line endpoints and use references to existing endpoints from sequence or proxy services.

Maintenance is easier when you isolate endpoint definitions from sequences and proxy services.

Security Guidelines and Best Practices

This section provides some security guidelines and best practices useful in service development.

• Use DMZ-based deployments. Also see  

http://wso2.com/blogs/architecture/2011/04/public-services-gateway-and-internal-services-gateway-patterns.

• Change default admin username and password.
• Change the default key stores.
• Secure plain text passwords and configure user password policies.
• In REST services deployments, secure your services with OAuth (Bearer and HMAC) and Basic authentication with HTTPS. This is recommended because:
• It adds authentication, authorization and validation in to the services.
• It enables communication to be done in a confidential manner while achieving non-repudiation and integrity of the messages.
• It helps you avoid attacks such as replay, DoS and to define rules for throttling the service calls.
• It helps you to control access to services in a fine-grained manner using role-based, attribute-based and policy-based access control.