API Management Design Standards

Table of Contents

Section1: API use cases.................................................................................................1

Section2: API design......................................................................................................3

Section3: API components............................................................................................5

Section4: API Service REST............................................................................................5

Section5: API Service SOAP...........................................................................................9

Creating an API Service component............................................................................12

Section6: API deployment...........................................................................................12

Section7: API testing...................................................................................................13

Section1: API use cases
Web service APIs can be constructed to facilitate common integration goals, such as event-based
integrations and the triggering of integration processes.

Develop event-based integration

Processes can automatically execute on a schedule as frequently as in one-minute intervals. If you

would like to limit the number of process executions and support real-time integration, you can
deploy a process that uses the Web Services Server connector to listen for requests. Here are some
common examples.

 Salesforce to database: Through Salesforce Outbound Messaging and Apex triggers,

developers can now configure SOAP/HTTP requests to be sent to an endpoint URL upon the
editing and/or saving of object records. You can enable a Boomi Atom in an on-premise
database environment to listen for these requests via its embedded web server and
translate the XML into database data that can be sent to a local database solution.

 Coupa to EDI: Coupa also supports the ability to build work flows and send XML requests to
an endpoint URL. You can use a Boomi Atom Cloud to accept these requests, translate the
data into EDI transactions, and send the transactions directly to a trading partner with other
communication protocols such as FTP or AS2. This type of scenario does not require the
usage of any on-premise resources and is fully supported in the cloud.

Enable mashup scenarios

You can leverage a web service API to facilitate the mashup of data from an unlimited number of
content sources in a variety of data formats. You can return formatted response data synchronously,
serve it up to other web service APIs or send it directly to a destination file resource or application.
For example, you could construct a single process that:

 Accepts user-defined requests

 Queries Salesforce for updated account information
 Polls an FTP directory for related flat file data
 Queries a local file for an account's invoice information
 Combines and translates the data in a desired format
 Sends a mashup of the results to a Salesforce custom object
 Updates an on-premise database application
 Returns an XML response synchronously to the client request application at any point in the
process flow
On-premise applications and resources

Web developers can use Boomi Integration to more easily integrate a variety of applications and
data sources with a web page or SaaS application. The Boomi Atom allows you to build a secure
pipeline to your on-premise applications and resources behind your firewall, enable a web server on
a specific URL and port, and send/receive SOAP and HTTP requests to then manipulate and serve the
data.

Note: Because data security is a top priority for integrations of this type.

Trigger integration processes

Input sent to an API endpoint linked to a Web Services Server listener process can be passed as
documents of any type, HTTP request headers, URL path parameters and HTTP query parameters.
The process can translate the input into other formats or simply send it to on-premise or hosted
destinations. The capability for clients to simply kick off a process by hitting the URL is also
supported. For this method of invocation, no input data is actually required. These options allow you
to not only spark integrations in a real-time fashion, but also prevent you from having to log into
the Boomi AtomSphere platform to manually execute a process.
Note: The Execute Process API also supports process triggering.

Proxy external web services

Web developers can use Boomi Integration to serve as a proxy for external web services. This type of
implementation enables an organization to manage, throttle and analyse API usage regardless of
where the underlying web services are deployed.

Enabling an Atom, Molecule, or Atom Cloud for use with an API Service component

Use the Shared Web Server panel within Atom Management to set the API Type to Advanced.

You must have the Atom Management privilege to perform this task. If you have the Atom
Management Read Access privilege, you cannot perform the task.

The API Management feature must first be enabled for the account that owns the Atom, Molecule,
or Atom Cloud.

Procedure

1. In the Manage menu select Atom Management.

2. Select the Atom, Molecule, or Cloud from the list on the left.
3. In Settings & Configuration, click Shared Web Server.
 The Shared Web Server panel opens.
4. In the API Type list, select Advanced.
5. Click Save.

Section2: API design

Each API endpoint configured in an API Service component must have an independently deployed
linked process that uses a Web Services Server connector operation to listen for and act upon API
requests. You can link the same process to any number of endpoints.

You can define endpoints in these ways:

 Select existing processes and generate the endpoints to which the processes are linked.
 Add endpoints individually and link processes to them.
 Simultaneously generate both a process and endpoints to which the process is linked.
 Import a WSDL for an external SOAP-based API. Simultaneously generate processes and
SOAP endpoints to which the processes are linked to serve as proxies for operations enabled
by that API.

The WSDL SOAP binding must be in the document style and have a literal use — that is, the
Document/literal style/use model; WSDLs whose bindings are in other style/use models are
not supported. WSDLs containing element definitions having the form attribute with a value
of “unqualified” are also not supported.

You can also generate SOAP endpoints analogous to existing REST endpoints and vice versa.

The default settings for an endpoint’s specified operation are derived from its linked process’
connector operation. By using the capability to define overrides for the operation’s default settings,
you can expose different sets of endpoints for use by different customers or partners.

Another way to customize an API Service component’s SOAP API is by assigning unique service
names and namespaces.

You should not deploy API Service components that specify objects for which a profile type conflict
exists. A conflict occurs when multiple referenced XML profiles include the same type and
namespace or when multiple referenced JSON profiles have the same root name. You can resolve
conflicts by standardizing on one profile. Profile conflicts are identified as you configure an API
Service component and lets you resolve conflicts before you finalize configuration.

API Service components do not directly include linked processes when deployed. Rather, requests to
endpoints invoke the currently deployed versions of linked processes.

Similarly, copying an API Service component from one account to another does not also copy the
component’s linked processes. The following actions, done in order, will result in a deployable copy
of an API Service component in a target account:

1. Copy the linked processes to the target account.

2. Copy the API Service component to the target account.
 3. In the target account, link the copies of the processes to the copy of the API Service
component.
4.
Processes linked to API endpoints generated by importing an external API’s WSDL are not bound to
that WSDL. If you deploy a proxy API generated in that manner and the owner of the external API
changes the WSDL, you have two alternatives:

 Reimport the WSDL in the API Service component, and regenerate the corresponding
endpoints and the processes to which the endpoints are linked. Then redeploy both the new
processes and the API Service component.

or

 Revise the processes and affected dependent components to reflect the WSDL changes, and
redeploy the revised components.

Section3: API components

There are two types of API components, both of which are deployable and created in Boomi
Integration on the Build page:

 API Service components define API endpoints.

 API Proxy components allow for the direct proxying of a request through an API Gateway to
a service which is not served through an Atom, Molecule, or Atom Cloud.

Section4: API Service REST

The API Service REST tab is used to generate and configure the API service’s REST endpoints.
Endpoints consist of a resource, which identifies an object, and a route, which specifies an operation
performed on the object. Resources have one or more associated routes. If you do not have any
REST endpoints defined

Path to REST: /ws/rest/myapp

Add an endpoint

Action – POST

For each item in the list there is an   Actions menu:

Name
Description
Path to REST
Shows the relative path for the REST endpoints that is pulled into the complete path (along
with the Base API Path from the General tab) when the web server is deployed to an Atom.
The Atom provides the base URL.
Action
Click on the   Actions icon to either edit or delete the endpoint or copy it to SOAP or
OData.
 HTTP Method
Shows the HTTP method used in requests for the operation specified in the route.
 GET — GET or QUERY operation.

 POST — CREATE, EXECUTE or UPSERT operation.

 PUT — UPDATE operation.

 DELETE — DELETE operation.

 PATCH — PATCH operation.

Note: The HTTP method used for an incoming REST request is available to the listener
process execution as the dynamic process property in method

Resource Path
Shows the resource path for requests for the operation specified in the route. The Resource
Path consists of two fields: Object Name and Path Parameters.

Object Name
Specified for when requests are made to the specified operation.
Path Parameters
Braces {} in the path, for example {id}, delineate the names of parameters. Parameters in the
matched part of the path are available to the linked process as dynamic process properties
named param_name, where name is the parameter name, for example param_id.

The full URL has this form:

http://Host:port/REST_url_path/Object/Path_Parameters
where:

 Host and port are set in the Shared Web Server panel (Manage > Atom

Management).
 REST_url_path is the Path to REST (this path contains the Base URL specified
in the General tab),
 Object/Path Parameters is this setting.

For example:

http://machine.domain.tld:9090/ws/rest/Customer/{customerId}

HTTP Method and URL path USAGE

GET / Return all instances of the object

GET /{id} Return the instance of the object having as its ID the specified
 parameter value
GET /{id}{fieldName} Return the value of the field specified as the fieldName
Parameter value in the instance of the object having as its ID the
Specified id parameter value
GET /{id}{metadata} Return metadata for the instance of the object having as it ID the
Specified id parameter value

By the same token, web services should also be consistently named according to a schema
determined at project inception. Some guidelines for web service naming conventions are as follows:

 Web service names should clearly indicate what they do from a client’s point of view.

 The HTTP GET method should only be used for data reads; it should not be used for calls that
update or change the state of data.

 Use query parameters to provide filtering, sorting, and paging if possible.

 Make sure to version your API, using the URL for the API versioning starting with the letter
“v”.
Example: /ucm/account/api/v1

 Make sure to handle errors using appropriate HTTP status codes; for example, for situations
where a request is submitted with inadequate or invalid query data, be sure to return an
HTTP 400 response code.

While REST APIs are extremely useful, creating them can be a time-consuming process. If you are
building your own REST or RESTful API, you should know that there are best practices to follow. This
includes the naming of your REST API endpoints.

There are basically ten guidelines that you can follow to make your API endpoints better:

1. Use nouns:
For Example
https://api.example.com/users/abcd-efgh-ijkl

2. Use intuitive, clear names:

For Example
https://api.example.com/users

3. Use lowercase letters

4. Avoid special characters:

For Example: %20

5. Use forward slash (/):

For Example
https://api.example.com/users/1234/first-name

6. Separate words with hyphens (-):

For Example
 https://api.example.com/users/1234/first-name

7. Don’t use file extension

For Example
.xml

8. Use camelCase for parameters:

For Example
https://api.example.com/users/1234

9. Use API versioning:

For Example
https://api.example.com/v1/users/1234/orders/2

Each API Type setting does and doesn’t do, as well as some ideas to help reduce any issues when
switching this setting in the future.

BASI INTERMEDIAT ADVANCE

C E D
Endpoint: /ws/simple/ x X
Endpoint: /ws/rest/ X
Endpoint: /ws/soap/ x X X
User Management X X
Web Service Component X
Web Services Server Operation x X **
Ability to Access API with
x X X
Token

BASIC

Primary use: When integrating “Web Services Server Operation” component (Listeners), and anyone
can hit the API (or with a specific token, which isn’t user specific).
Available Endpoints:

 /ws/simple/
 /ws/soap/

*If planning on implementing API components anytime in the future, endpoint “/ws/soap/” is
recommended.

INTERMEDIATE

Primary use: When integrating “Web Services Server Operation” component (Listeners), and only
specific users can hit the API.
Available Endpoints:
  /ws/simple/
 /ws/soap/

*If planning on implementing API components anytime in the future, endpoint “/ws/soap/” is
recommended.

ADVANCED
Primary use: When integrating API component.
Available Endpoints:

 /ws/rest/
 /ws/soap/

*Note, when you use “ADVANCED”, the /ws/simple/ endpoint gets disabled and will no longer work.

Section5: API Service SOAP

The API Service SOAP tab is used to configure the API service’s SOAP API and to generate and
configure its SOAP operations. If you do not have any SOAP operations defined, you are prompted to
Create one

Name
Description
Path to SOAP
 Shows the relative path for the SOAP operations that is pulled into the complete path (along
with the Base API Path from the General tab) when the web server is deployed to an Atom.
The Atom provides the base URL.
Note: Endpoints can be generated from processes by clicking Import an Endpoint in the
component and selecting the processes. The default settings for the specified operations
are derived from the process’ Web Services Server connector’s Listen action.

SOAP advanced settings

The following advanced settings are related to the SOAP API’s WSDL, which is automatically
generated and defines the required structure for all SOAP requests and responses.

Name
Description
WSDL Namespace
Identifies the unique namespace identifier that is applied as a prefix in the WSDL to object
names and list nodes.
Schema
 Single — schemas are embedded in the WSDL.

 Multi — a schema file is generated for each XML namespace. Schema files are linked
from the WSDL or another schema file.

WSDL Service Name

The WSDL service name affects the <port> and <binding> elements in the WSDL.
It is typically unnecessary to set a custom value unless you have a requirement to mimic a
pre-existing API.

SOAP Version
Sets the SOAP version compatibility for the WSDL:
 1.1 (default) — the WSDL is compatible with SOAP v1.1.

 1.2 — the WSDL is compatible with SOAP v1.2.

 1.1 and 1.2 — the WSDL is compatible with both SOAP v1.1 and v1.2.

Omit Operation Wrappers

If specified, the WSDL omits Boomi-specific operation name wrapper elements for requests
and responses. This setting is off by default, and Boomi adds a wrapper around the profile
object to identify the operation.
A standard operation structure is expected to be <operationName><ProfileObject> content
of ProfileObject </ProfileObject></operationName>. If the profile root node already
describes the operation, which is especially true when the root node is interacting with pre-
existing third-party APIs, the default <operationName> wrapper should be omitted.
This option cannot be used with operations for which the input type is Multiple XML objects.
This option cannot be used unless operation names match the names of their corresponding
profile elements.
 Note: Advanced SOAP functionality is an optional account feature. If you would like to
have this feature enabled in your account, contact your Boomi representative.
SOAP Envelope Passthrough
If specified, the entire SOAP request is passed into the process. If not specified, only the
SOAP body section is passed into the process.
Use this option for examining the entire SOAP request or for processing SOAP header values
within a Boomi process. For example, the SOAP header WS-Security can be called in a
process when SOAP Envelope Passthrough is specified.

Note: Advanced SOAP functionality is an optional account feature. If you would like to

have this feature enabled in your account, contact your Boomi representative.
Upload Custom WSDL
Allows you to override the generated WSDL with one that provides different namespaces
than the auto-generated ones. This is particularly important if clients of your web service are
expecting the namespaces in a specific format different than the Boomi-generated ones.
If you choose to upload a custom WSDL, the uploaded file is returned exactly as indicated so
that you have a seamless match to the original. You are required to update the WSDL in
order to show new objects that you have added or to remove objects that you have deleted.
Note: Uploaded or imported files are first passed through a virus scanner. The upload or
import results in an error if a virus is detected, and the file is rejected. If an error
persists, contact Boomi Support.
With a custom WSDL, it is your responsibility to match all operations and processes to the
uploaded WSDL.

Note: Advanced SOAP functionality is an optional account feature. If you would like to

have this feature enabled in your account, contact your Boomi representative.

SOAP operations
Operations are listed by operation name. Selecting an operation enables the controls to the right for
configuring the operation specified for the endpoint.

Name
Description
Action
Click on the   Action icon to either edit or delete the operation or copy it to REST.
Operation Name
 When a process is linked to an endpoint, the operation name is derived by default
from the process as follows: The listener operation’s type is concatenated to the
name of the object — for example, getCustomer. The derived operation name
appears in gray.

 If the endpoint is not linked to a process, the operation name is set by default, as an
override, to operationNameX, where X is a sequentially assigned numeric
character(s).
 Typing an operation name overrides the default. If an override is set, the operation name
appears in black.

If the Pure SOAP Passthrough option is selected, the operation name must match the name
of the corresponding profile element.

Process
Shows the Web Services Server listener process linked to this operation.
Operation Description
Description of the SOAP operation.
Operation configuration
Properties of the selected endpoint’s specified operation are configurable.

Note:
When a process is linked or edits are applied to a linked process, the settings for the operation are
updated to match the process’ Web Services Server connector’s Listen action, thereby negating
previously set overrides.

Note:
To update the endpoints list to reflect operation configuration changes, you must Save the
component.

Creating an API Service component

Create an API Service component in Boomi Integration on the Build page.

Procedure
1. On the Build page in the Component Explorer, navigate to the folder in which you want to
create the component.
2. Click the blue arrow   next to the folder.
3. Click the   New Component link.
The Create Component dialog opens with the folder selected.
4. In the Type list, select API.
5. In the Component Name field, type a name for the component.
The maximum length is 255 characters.ap
6. In the API Type list, select API Service.
7. Click Create.
The component appears on a tab with the name you entered.
8. Optional: Type a description.
9. Click Save.

Section6: API deployment

In order to begin testing from a client application and successfully reach the full URL path defined in
the Atom and operation, you need to deploy an instance of the web service listener process. If the
endpoint is defined in an API Service component, you need to deploy that component as well.
It is recommended that you deploy an early version of the listener first to confirm that the URL is
working before fully developing the process from end to end. There are some networking
considerations when trying to reach the URL in the Cloud or behind your firewall in a local
environment. See the topics linked below.

You can view the status of deployed listeners and API Service/Proxy components in the Listeners
panel in Manage > Atom Management. In that panel it is also possible to pause, resume, and restart
listeners.

Section7: API testing

You cannot use Test mode within an API process because the Web Services Server connector is
listen-only and cannot be triggered in real time when in this mode.

Here are the basic steps to test an API process:

1. Deploy the process to an Atom Cloud or to a local Atom to launch Web Services Server.
2. If you are using an API Service component to define the API endpoint(s), deploy the
component.
3. Trigger the client application work flow that invokes the API by sending an outbound
message to the Atom's endpoint URL.
4. Review the process execution and inbound document data on the Manage menu's Process
Reporting page. A new execution thread should be visible after a successful send from the
client application to the Atom's web server.
5. Save a copy of the inbound request data to a local file.
Consider using the FTP or Disk connector in the Start step to retrieve the request XML, JSON, or file
data that you intend to send through the API process. This allows you to simulate the document flow
in Test mode without having to fully deploy the process to an Atom.

Client-side testing with RESTClient

POSTMAN enables you to work interactively with API clients or implementations and to run tests of
REST-based APIs in a continuous integration environment. It is best to use RESTClient to test APIs
processes where the full REST URL is available.

Client-side testing with SoapUI

SoapUI is a testing tool that enables you to work interactively with API clients or implementations
and to run tests of SOAP-based APIs in a continuous integration environment. It is best to use SoapUI
to test APIs processes where the full SOAP URL is available. Consider getting the SoapUI NG Pro
version to do more extensive testing with HTTP messages.

Building a SoapUI project

Using SoapUI, you can test APIs by pointing to the WSDL URL.
Procedure

1. Select File > New SOAP Project.

The New SOAP Project dialog opens.

2. In the Project Name field, type a project name.

3. In the Initial WSDL field, type or paste the WSDL URL that points to the Atom web server
URL or the domain name for a Boomi Atom Cloud or Test Atom Cloud. 

Note: Ensure that you have a process deployed to the Atom that contains a Web Services
Server connector.

4. Turn on the Create sample requests for all operations? check box.

5. Click OK.
6. If you are using BASIC authentication or are connecting to a Boomi Atom Cloud or Test Atom
Cloud, enter your Account ID and the Atom's authentication token (see the topic Configuring
Web Service Listen Connections) and click OK.
At this point, all web service request operations from the Atom's web server will load into
your SoapUI project.

Building a SOAP request in SoapUI

In SoapUI, build a SOAP request by editing the request to include your Boomi AtomSphere

platform information.

Procedure
 1. Collapse one of the requests in your project list and right-click Request 1.

2. Select Show Request Editor from the list.

3. Edit the SOAP request as required and enter sample data where there are question marks.

4. If you are using BASIC authentication or are connecting to a Boomi Atom Cloud or Test atom
Cloud. enter your AccountID and the Atom's authentication token in the Username and
Password fields in the Request Properties section.

5. Click the green arrow button in the top left corner of the request editor to send the request
to the endpoint URL.

6. Review the response window on the right to see messages returned from the web server.

7. Optional: Consider adjusting the timeout parameter (in milliseconds) if you need the client
to wait longer for responses.




 Building a REST request in RESTClientBuilding a
REST request in RESTClient
Building a REST request in RESTClient

Using RESTClient, configure a REST request by entering your Boomi AtomSphere

platform information into the request.

Procedure

1. In the URL field, type the endpoint URL for the request.

2. In the Method tab, select the HTTP Method for the request.

3. If you set HTTP Method to POST or PUT, select the Body tab and type the request body in
the box.

4. If you are using Basic authentication or are connecting to a Boomi Atom Cloud or Test Atom
Cloud, select the Auth tab and do the following:
a. In the Auth Type section, turn on BASIC.
b. In the Username field, type your Boomi user ID (email address).
c. In the Password field, type your Boomi password.

5. Click   Go.
RESTClient sends the request to the endpoint.

6. In the HTTP Response panel, review the Status returned from the endpoint, examine the

returned HTTP headers in the Headers tab, and, if applicable, review the response body in
the Body tab.

7. Optional: To save the request for repeat use, select File > Save Request and in the Save
Request dialog, specify the disk location for the request (.rcq) file.