API Design and Service Naming Standards

-Mule (3.x)

Revision History

Revision No. Date Changes Author

0.1 23-July-2018 Initial draft Debasish Das

Table of Contents
1. Introduction
2. Service (API) Naming
2.1. Service naming
2.1.1. Domain
2.1.2. Categories
2.2. URI Design
2.2.1. Handling Actions
2.2.2. Parameters
2.2.3. Versioning
3. Mule Naming Standards
3.1. RAML
3.2. Mule project
3.3. Mule flows
3.4. Connectors
3.5. Data mapper
3.6. Variables
3.7. Other mule component naming
4. Documents Naming
5. Appendix
5.1. Glossary
Introduction
Purpose
A naming standard is a set of rules to identify the character sequence for different building blocks of a software. If a service follows the
defined consistent naming conventions, then outcome will be highly reusable service which can be consumed by multiple service consumers.
Using the naming conventions has the following benefits:

1. To help formalize expectations and promote consistency within and outside of development team.
2. To provide additional information (i.e., metadata) about the use to which an identifier is put;
3. To enhance clarity in cases of potential ambiguity;
4. To provide meaningful data to be used in project handovers which require submission of program source code and all
relevant documentation
5. To reduce the effort needed to read and understand source code
6. To enable code reviews be able to focus on more important issues than arguing over syntax and naming standards.
7. To enable code quality review tools be able to focus their reporting mainly on significant issues other than syntax and style preferences.
8. To enhance source code appearance.
9. To provide better understanding in case of code reuse after a long interval of time.

Audience
This document is intended for

Development teams.
QA teams.
Deployment and Support teams.

Service (API) Naming

Service naming
The Services should be named either after a domain or a combination of domain and category, an incomplete list of domain and category follows.
Layered Implementation
The recommended naming for Services implemented as layers are as follows.
<MicroserviceName>-<layer identifier>-api
The Layer Identifiers are

Layer Identifier

Experience exp

Process prc

System sys

e.g. offer-exp-api, order-prc-api, menu-sys-api

The domain Identifiers should be derived from the Enterprise Domain model; a short list is available below.

Domain
Please refer the enterprise business domain model. Below are some examples:

Customer
Restaurant
Marketing
Commerce
Sales
Technology

Sub-Domain
Please refer the enterprise business domain model. Below are some examples:

Accounts
Loyalty
Favorites
Application
Offer
Location
Order
Session
Feedback
Customer Master Data
Search
Purchase
People
Authentication
Content
Delivery
Music
Merchandise

URI Design

Best Practices
1. As a best practice and industry standard practice for RESTful style interfaces, the API resources should be named using nouns and
not verbs in their base URL. This practice is important because it helps to keep the total number of interfaces down; promotes a
consistent and easy to understand approach, and helps to encapsulate common functionality under a single resource.

Bad Good

/findStore /store/location
 /deleteCustomer /customer
/object /store

2. The name of a resource should clearly describe the object or resource in which the backend service exposes. It is important to use the
right level of abstraction to clearly describe the resource that is being modelled in the context that it is being used. Adding a domain to
the URL path also helps to associate a resource with a specific logical domain.

Bad Good

/eCP/securityToken /security/token

/DEP/nutrition /product/nutrition

/object /store

3. Use proper methods to indicate the action, the following methods are recommended
a. GET
b. POST
c. PUT
d. PATCH
e. DELETE
4. While not a REST Standard, it is recommended to not use any variables in the URI. The recommended practice is to use the
query parameter for GET and DELETE and body for PUT, POST and PATCH

Bad Good

GET/customer/456/redemption GET/customer/customerid/redemption/?cutomerid=456

POST/restaurant/st5678/location POST/restaurant/storeid/location
{
{ "storied":"st5678"
"hello":"world" "hello":"world"
} }

Consideration's for Layered Implementation

In Mule, API will be implemented as 3 layers' experience, process and domain/system layer
Experience API URL Naming
At the experience layer the URI naming convention should be
{Baseuri}/{version}/{experience}/{Domain}/{Sub-Domain}/
Where the value of {experience} in agreement with business for that specific experience else by default would be 'exp'. Subdomains are
optional.
For example: https:/<appname.cloudhub.io>/v1/exp/customer/redemption
Porcess API URL Naming
At the process layer, the API would encapsulate the orchestration logic of the process and hence may not follow the previous rule of
using only nouns. The URI naming convention should be
{Baseuri}/{version}/process/{Domain}[/{Sub-Domain}]/{Process Name}
Where the value of {Sub-Domain} is optional depending on if the process is defined at the Domain level or sub-domain level
The would be only one implementation of the process across the enterprise and hence there are no variation to the 'process'
For example: https:/<appname.cloudhub.io>/v1/process/commerce/customer/dedup
https:/api.org.com/v1/process/commerce/tag_customer_to_offers
System API URL Naming
At the domain/system layer, the URI naming convention should be
{Baseuri}/{version}/{Domain}/{Sub-Domain}
For example: https:/api.org.com/v1/commerce/customer
https:/<appname.cloudhub.io>/v1/commerce/offer/redemption

Handling Actions
In REST, actions on a resource are implemented by the HTTP methods (GET/POST/PUT/DELETE) used when the web service is called.
These methods map to the CRUD model and dictate what actions to perform on the resource.

CRUD Action HTTP Method

(C)reate POST

(R)ead GET
 (U)pdate PUT or POST
(D)elete DELETE

For example, the \deleteCustomer from above can be implemented/mapped to a REST style API call using an HTTP DELETE to
the customer resource.
The delete URL would look something like this:
\customer?id=12345
The URL to read the customer record 12345 would look the same except it would be submitted as an HTTP GET request.

Parameters
Under REST there are several different ways to pass parameters to resources for a read & delete (HTTP GET & DELETE) request. To
maintain a consistent and an easy to understand approach, all parameters will be passed on the URL as a query string as a name/value
pair after the "?". For example:
/product/nutrition?id=12345
For insert and update (HTTP PUT & POST) will pass objects as JSON formatted documents in the body of the HTTP request. For
example:
{"id":"12345","name":"customer1"}
Lists can also be supported by passing in an array of JSON documents.
[{"id":"12345","name":"customer1"},{"id"="23456","name":"customer2"}]

Versioning
The endpoint URL for a service, which is the address that a consumer uses to locate and invoke a service, must reflect the major
version number only. This is because the inclusion of a minor version number would cause the address of the service to change for each
minor version release, thus making the service appear to have been removed, from an existing consumer's perspective.
The service's major version (prefixed with 'v') must be included in the endpoint URL of the address that consumers use to invoke the
service.
Example:

for a service, a typical URI could be

/v1/store/location
For the next backward compatible release there is no change in the URI, but for a backward incompatible major release the URI
should be updated to
/v2/store/location
The URL could be derived by adding the protocol and hostname.
http://<hostname>/v2/store/location

Mule Naming Standards

Mule ESB comes with multiple building blocks such as mule processes known as flows, sub flows, transformer components, filter
components, router components and various types of connectors. This section will put the naming standards in place for all
these components so that any ambiguity can be ruled out between the codes of two different developers.

RAML
A RAML file is an integral part of an API, The RAML should be named with just the Service name.
<ServiceName>.raml
< ServiceName > is the name of the service for which this file is being created. E.g. Store
The version number of the file should not be included in the name, if needed version should be maintained as a comment
Example:
Example:

#%RAML 0.8
title: Store
baseUri:
http://api.na-org.com/\

{version}
version: v4
#fullVersion: v4.3.1
Mule project
Mule project are the basic building block and can be considered as the briefcase containing other mule artefacts like mule flows, RAML
files, schemas, sample request response json files and other connector specific libraries. Mule project names should be the same as
the service name. Avoid putting the version in the project name, it is best managed in the source control. Recommended to use all
lower case.

Mule flows
A Mule project can contain more than one flow or sub-flow. If project is generated using RAML file then each flow will have a default
name which is recommended to change. Hence each flow should be named as per the function it is going to perform. The flow can be
named with a verb (as per the HTTP method) followed by optional domain and the noun and then in the end will come the keyword 'Flow
For example:

Format Example

<verbDomainResourceFlow> getStoreLocationFlow

<verbResourceFlow> createCutomerFlow

If it is a sub-flow then flow keyword should be replaced with the SubFlow keyword keeping everything else same.
For Example:
getCustomerIdSubFlow
Recommended to use camel case.

Connectors
Mule flows will have connectors to connect with other applications. These connectors should be named as per the operations invoked
on the target system followed by the name of the target system separated by an underscore (_). It must not contain the protocol
information or implementation details of the connector. For example:

Format Example

<operationName_TGTSystemName> getCustomerInfo_CRM

<operationName_TGTSystemName> getStoreLocation_DB

Recommended to use camel case.

Data mapper and Data weave

Data mapper is mule component used for transforming the data from one format to another. A data mapper component can be named
by using the output message names as below. For example, when we receive the customer data, it might also contain the contact
details and the target system keeps the customer and contact as different entities then it should look like:

Format Example

map<outputMessage> mapContactRequest

map<outputMessage> mapCustomerResponse

Recommended to use camel case.

Variables
Mule has the variable, session variable and record variable components to set (create) or delete the variables in a flow. These variables
are used to keep the required data with them during the processing of the flow. Below are couple of rules that determine the naming of
a variable:
 5. Variable name should not contain the numbers.
6. Variable name should not be abbreviated to the extent that it is hard to recognize the meaning of it. For example, a variable
containing customer id should not be named as CI while it can be named as custId or customerId.
7. It should be using the camel case notation.
8. It should be explanatory on what data it is holding. For example, customerDetails, storeName, itemId are all valid names.

Above points give us the naming patterns for the variables while components itself can be named as keyword 'set' followed by the variable nam
For example:

Format Example

<setVariableName> setCustomerId

<setVariableName> setOrderId

Other mule component naming

All other mule component being used in the flow can be named as per their functions being performed. These names should be self-
explanatory. A developer should avoid very lengthy names. The name should not be containing the implementation details, data types as well.
Couple of examples are as below:

Component name Example

Set Payload setCustomerDetailsAsPayload

Property setContentTypeProperty

Byte Array To String deserializeRequest

Logger logCustomerDetails
Appendix
Glossary
The following table lists the glossary of terms used in this document.

Acronym Description

API Application Program Interface

ESB Enterprise Service Bus

HTTP(S) Hypertext Transport Protocol (Secure)

RAML Restful API Markup Language - see http://raml.org

REST Representational State Transfer

SOA Service Oriented Architecture

XML Extensible Mark-up Language

SOAP Simple Object Access Protocol

Application A named entity which uses APIs for which proxies have been created and deployed in API Gateway.

Endpoint Refers to a location in either MuleESB or APIGateway which can receive incoming requests. Not all endpoints are accessible
from outside the application.In the API proxy case, endpoints are mostly HTTP/S."Endpoint" is often used as a term for a specific
"method" of an API.

Method Refers to a specific combination of:- relative URL (relative to the base-path of the API Gateway deployment- HTTP verb (GET,
PUT, POST, DELETE)

Component Mule has various visual components that perform a predefined operations depending upon the configuration done during design
time. A developer can select the desired component from the respective palette in IDE and can edit in the canvas (editable area).
These components are intertwined together to perform a business task.