The 10 step guide outlines the process for designing API integrations between applications and cloud services. The steps include: selecting services for integration, authenticating with services, discovering service data structures, mapping data between services, transforming data formats, implementing CRUD operations, enabling browsing of service data, syncing data changes through events, logging integration activity, and maintaining the integration as services evolve. Following these steps provides a common pattern for interactive integrations.

2. THE 10 STEP GUIDE TO API INTEGRATIONS
Product Owners and App Developers are frequently tasked with
designing API integrations between their apps with the cloud
services used by their customers, partners or employees.
Integrating your app with cloud services such as Dropbox, Google
Drive, Salesforce.com, Jira and Quickbooks can provide your users
with a “cooperative” experience in which they can seamlessly share
data between your app and the other cloud services they use on a
daily basis.

3. This new era we’re entering envisions cooperative,
or connected, applications via cloud-based API
integrations.
Follow this 10-step guide, reflecting a common
pattern for interactive integrations between your
app and other cloud services.

4. Where in your app will the
user select service
endpoints they want to
connect with your
application?
1.
SELECT

5. 1. SELECT: OPTIMIZE USER EXPERIENCE
- Are end-users or administrators going to be setting up the
API integration?
- Is it a one time setup or is on-going interaction required?
These and many other factors will drive the optimal
interface to present your users in selecting the services
they want to connect with your app.

6. Determine the type of
authentication mechanism
used by the endpoint and
the workflow required.
2.
AUTHENTICATE

7. 2. AUTHENTICATE: SECURE AUTHENTICATION
- Manage the workflow for authenticating to each instance of an
API endpoint that your users are connecting with your app
- Determine the type of authentication mechanism the endpoint
will use (e.g., OAuth, SAML) and the workflow required by the
endpoint
- Do you need to keep the authenticated instance active?
- What’s the refresh key process for each end-point and how will
you manage the keys?

8. Discover which objects and
data fields (e.g. data
structure, field names and
formats) need to be mapped
into your application.
3.
DISCOVER

9. 3. DISCOVER: USING DISCOVERY APIs
Many services provide a method to discover the objects and
data fields at the endpoint to provide the data structure, field
names and formats that need to be mapped into your
application
- Determine which objects and data fields that are relevant
to your application. Often this is a subset of the available
data at an end-point

10. Many SaaS service support custom
data objects and data fields that
your customers would like to share
with your application.
Consider if your integration design
needs to accommodate discovery and
mapping of these custom data objects
to your data model.
4.
CUSTOM DATA

11. 4. CUSTOM DATA
Does your integration design need to accommodate discovery
and mapping of custom data objects to your apps’ data
model?
Many integration end-points provide automated data
discovery of custom objects but with others you may need to
provide a manual means for your users to map these objects
into your application.

12. First, provide default mapping
from the endpoint’s standard
data structure, by pre-mapping
obvious data fields. Next, provide
your users the ability to map
custom objects .
5.
MAP DATA

13. 5. MAP DATA
A Two Step Process:
1. Provide a default mapping from an endpoint’s standard data
structure into your application’s data structure. This will save your
users time by pre-mapping obvious data fields such as name,
address, postal code, etc.
2. Provide your application’s users with the ability (generally through
a UI) to map custom data objects and fields into your application.
Through this UI you may also consider providing the ability to
override your default mappings.

14. Your app may use different
formats for data values, such as
date, time, or currency. You
may need to translate these
values into the appropriate
formats used within your app.
6.TRANSFORM DATA

15. 6. TRANSFORM DATA
- Your application may use different formats for data values
such as date, time or other forms of data
- Transformation services may be required to translate the
data between your app and the endpoint’s data structure to
ensure integrity of the data
As with data mapping, your application will need to persist the
transformations for each instance of an api endpoint that your
app is connecting with.

16. Determine the methods your app
needs to execute against each data
object (CREATE, RETRIEVE,
UPDATE, DELETE, SEARCH).
Consider which app will be mastering
the data vs. consuming the data to
avoid conflicts.
7.
CRUD(s)

17. 7. TRANSFORM DATA
Consider which app will be mastering the data vs. consuming
the data to avoid conflicts and having to manage more complex
data synchronization scenarios. Often you can start with a
read-only integration and then introduce update and delete
methods as you mature your integration.

18. Consider how users will
interactively engage with data
(e.g. selecting files, searching
records, ect.) through a user
interface, offering a seamless
integration experience.
8.
BROWSE

19. 8. BROWSE: IMPLEMENT SEARCH, BROWSE, SELECT
Will users need to interactively engage with data in the endpoint
to perform the CRUD(S) operations?
Interactions may include selecting files or data records,
updating or deleting data from the endpoint to provide a
seamless integration experience for the user from within your
application.

20. Do you need to synchronize data
between your app and the
endpoint? Many endpoints support
webhooks to keep your application
up-to-date as new data is added,
deleted or modified.
9.
EVENTS & SYNC

21. 9. EVENTS AND SYNCHRONIZATION
Determine if you need to synchronize data between your
application and the endpoint.
Many integration endpoints support webhooks that can be used
to simply automate the workflow keeping your application
up-to-date with changes (events) at the endpoint such as new
data being added, deleted or modified.

22. Capture usage and log data
to support the integration so
your operation team can
monitor alerts and
notifications.
10.
LOG

23. 10. LOGGING AND API MONITORING
How will you support and manage the integration?
You will need to capture usage and log data to support the
integration to keep your operation team in the know. Determine
how to handle alerts and notifications from the endpoint
regarding service outages, API changes, etc.

24. All 10 Steps to Designing an
API Integration. After you
design the integration, you
have to maintain it.
THAT’S
IT!

25. API INTEGRATION MAINTENANCE
APIs change frequently, so develop a strategy now for staying on
top of changes introduced by the services you are connecting. This
includes managing version control, to ensure your integration
doesn’t break as changes are introduced.
Meanwhile, if you need help creating a killer cooperative app, try
Cloud Elements. Browse our free online resource, The Definitive
Guide to API Integration, to help you every step of the way.

26. Meanwhile, if you need help
creating a killer cooperative
app, try Cloud Elements.
Browse our free online resource,
The Definitive Guide to API Integration
to help you every step of the way.