303 BROUGHT TO YOU IN PARTNERSHIP WITH

CONTENTS

API Integration
•  About API Integration

•  API Integration Patterns

−  Error Codes

Patterns
−  Granularity and KISS Principle
−  URLs
−  Authentication
−  Querying
−  Pagination
−  Bulk
−  SDKs
UPDATED BY THOMAS JARDINET
IT ARCHITECT AT MANPOWER •  Additional Resources

PREVIOUSLY UPDATED BY BRIAN BUSCH

ABOUT API INTEGRATION vs. REST, XML vs. JSON, different auth mechanisms, workarounds for
APIs can be deployed from anywhere — from your on-premise and SaaS migrations, webhooks vs. polling for eventing, unique error codes,
applications to third parties. You first need a solid idea of which APIs limited search and discovery mechanisms, etc. Further, every data
you will use, allowing you to then go in depth into design and usage model is unique, requiring developers to solve complex data mapping
patterns from that perspective. The deployment architecture for your and transformation problems for each integration.
API management solution depends on this as well. Are the majority
With these challenges in mind, let's review key patterns to follow as you
of your exchanges on-premise? Your API management will have to be
build and maintain your API integrations.
on-premise. Or are they in the cloud? Same logic! And if it's both? The
deployment architecture can be in the cloud, or it can be a hybrid of ERROR CODES
cloud and on-premise.
PATTERN Respect HTTP error codes.
Opportunities for third-party APIs are not always considered at the
beginning of an API management project, which pushes the focus When creating integrations, it's important to understand what error
of deployment to the cloud. However, the diversity of APIs already codes you might be getting from the application provider. As you start
available is extensive and can easily bring differentiating functionality sending requests, it's helpful to understand when things work, but it
to your business. These third-party APIs can either be called directly becomes equally important to understand why they don't.
from a browser, from your corporate website, or from your API
management solution, including for API composition. For third-
party APIs in particular, it's important to consider both the pricing
model as well as the service-level agreement (SLA), seeing as if you
require an SLA of 99.9% for an API, you cannot depend on an API with
an SLA of 99.5%.

Once you have thought about your integration strategy, it is time to

design your API integrations, respecting key foundational patterns that
you should observe.

API INTEGRATION PATTERNS

It's often said that connecting to an API is easy, but secure integrations
that deliver seamless, effortless, and highly performant user
experiences are hard. Every API is unique: Researching and building
integrations means peeling back layers of nuance, including SOAP

REFCARD | MARCH 2022 1

Radar helps
develcpers auild
aest-in-class
lccaticn-aased
experiences fcr
their apps. s

Privacy-first Developer-friendly Enterprise-ready

Radar’s industry-leading geofencing platform helps

developers build location-powered experiences.

Geofencing and Place Detection

Pndustry-leading accuracy with unlimited gecfencesh pclygcn

gecfencesh and placeh regicnh and aeaccn detecticn.

Trip Tracking

Turnkey dashacards and appsh integraticnsh and flexiale SDKss

and APs fcr pickup and delivery tracking.

Search and Geocoding APIs

Flexiale and afcrdaale gecccdingh searchh and distance APss

with high-quality address and place data.

By the numbers

100M+ 100B+ $85.5M

installed devices lccaticns prccessed per year funding raised

Rešuest a demo today

 REFCARD | API INTEGR ATION PATTERNS

With integrations, error codes resulting from a lack of access to size And of course, at least for debugging reasons, you should add an error
limitations help guide your application's business logic as well. structure — i.e., with a dynamic error message and code contained in a
dedicated structure:
As the majority of HTTP error codes are standardized by RFCs, it is
important to respect them and to have an exhaustive, precise list Responses:

at your disposal. The following table describes the main HTTP error 400':
description: Bad request
codes, but it's advisable to rely on a complete and up-to-date list, such
content:
as the one from Mozilla:
application/json:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Status schema:
$ref: '#/components/schemas/Error'
Table 1

ERROR CODE DESCRIPTIONS GRANULARITY AND KISS PRINCIPLE

1XX Informational 302 Temp. Found 410 Gone Keep your API simple and readable; aim for medium-
PATTERN
grained resources.
2XX Success 303 See Other 411 Length Req.

3XX Redirection 304 Not Modified 412 Precondition Granularity and KISS principles work together hand in hand. KISS, for
"Keep it simple st*!" will drive you to define one granularity policy —
4XX Client Error 307 Temp. Redirect 413 Entity Too Big
one that will be the simplest for the end user: the developer who will

5XX Server Error 400 Bad Request 414 URI Too Long consume it! Below is an overview of design paradigms under KISS:

•  Design your API with your clients and developers in mind; do not
200 Executed 401 Unauthorized 415 No Media Type
copy/paste your own data model (at least for security reasons...).
201 Created 403 Forbidden 417 Failed
•  Design your main use cases first, then others after.
202 Accepted 404 Not Found 500 Internal Error •  Design using common terms, not business verbiage.

204 No Content 405 Not a Method 501 Not Implemented •  Design with the idea in mind that developers should have only
one way to implement functionalities.
301 Permanent Move 406 Not Accepted 503 Unavailable
With this mindset, fine- and coarse-grained APIs do not align well.
Fine-grained APIs will give you extra effort for no gain, as you’ll need
However, simply mastering the error codes is not enough. Consumers
to discuss how a resource should be categorized, regarding all the
do not have to guess all the error codes you implement in your API.
others resources you have or should expose — all of this just to get a
It is advisable to document the errors implemented directly in the
longer URL.
definition of your swagger description file.

Meanwhile, coarse-grained APIs will give the impression that your API
Here's an example of describing responses, which shows how to
is a mess because you’ll have resources at the same level, even if there
document your error codes:
are no relations between all those resources. To demonstrate these
responses: differences, let see some examples for a pet shop.
'200':
description: OK. Don't:
'400':
//Fine grained
description: Bad request. Parameter should be
Get /animals/mammals/omnivores/cats
a string.
'401': //Coarse grained
description: Authorization failed. Get /cats
'404': Get /payments
description: Not found.
'5XX': You must then aim for medium-grained APIs. Typically, an API resource
description: Internal error. whose structure contains no more than two levels, for example, is a
suitable level of granularity.

REFCARD | MARCH 2022 3 BROUGHT TO YOU IN PARTNERSHIP WITH

 REFCARD | API INTEGR ATION PATTERNS

For a pet shop, do: programming, you would have a customer class containing addresses
classes — you handle API resources the same way. So based on our
Get /animals/cats
example, to get a customer's addresses, you call the customer number
"id" and then addresses:
Or:
Get /customers/042/addresses
Get /animals/42
{
"id":"42", CONSISTENT CASE
"animalType":"cat" You must define your naming conventions — in particular, a "case
"cat": policy" that determines a consistent letter case across all resources,
{ as users shouldn't have to read your documentation every five minutes
"mustacheSize":"7",
to know which case is required for a specific resource. For parameters,
"cuteness":"maximum"
snake_case and camelCase are often used. While there’s no true reason
}
to favor one over another, developers often prefer camelCase because
}
it is deeply used in Java, while snake_case is easier to read by non-
techies. Meanwhile, spinal-case is preferred for URLs as some servers
With all of this in mind, anyone should be able to use your API without
don't respect case.
having to refer to the documentation, which should be one of your
ultimate goals.
Here are examples of each case:

URLS •  camelCase – Get /customers?countryCode=US

Use nouns instead of verbs, establish a hierarchical •  snake_case – Get /customers?country_code=US

PATTERN structure, maintain naming conventions, include versions,
•  spinal-case – Get /vip-customers
and employ proper HTTP methods.

VERSIONING
SINGULAR AND PLUR AL NOUNS Version must be contained in URLs in order to help developers migrate
Contrary to the SOAP philosophy, REST principles are designed around easily from one version to another. For those who didn't have the time
resources, and nouns should be used in most cases. to migrate, you also risk breaking client integrations for their
applications. Versioning is crucial, and the simplest method is to
Do:
include it in the URL. This way, API calls are logged on your servers, so
Get /orders
you’ll be able to see easily which version of the API was called, even if
you don’t have access to the consuming application.
Don’t:
You cannot be sure that everyone is able to migrate quickly to the latest
Get /Getorders
version, so maintain backward compatibility and support at least two
previous versions:
Finally, using plural nouns instead of singular allows you to handle
collections of resources and single resources at the same time. Get /v1/customers
Get /v2/customers
Do:

Get /orders HTTP METHODS

Get /orders/042
You must use HTTP methods (i.e., verbs) for their designated purposes.
From the beginning, HTTP was designed around resources, and it
Don't:
describes HTTP methods in order to execute specific actions for a
Get /Getorders resource.

GET retrieves data about a resource. For a collection:

In this way, you can keep a consistent and easy-to-use structure.

Get /customers
HIER ARCHICAL STRUCTURE
200 OK
Your resources should have a structure, and you should use the URL [{"id":"42", "name":"John Doe"},
path to get the details you need. For example, let's say a customer is {"id":"43", "name":"Elisa Re"}]
defined by their own ID, name, and address. As done in object-oriented

REFCARD | MARCH 2022 4 BROUGHT TO YOU IN PARTNERSHIP WITH

 REFCARD | API INTEGR ATION PATTERNS

For a single instance: application, and the service provider. In this flow, the user grants the
consumer (i.e., the application you want to be integrated) access to the
Get /customers/42
200 OK
service provider by an exchange of tokens through the OAuth endpoint

{"id":"42", "name":"John Doe"} before accessing data from the API.

Figure 1: OAuth workflow

POST creates a new resource. For a collection:

POST /customers {"name":"John Doe",

"countryCode":"US"}
201 Created
Location: https://myapi.com/customers/42

PUT replaces or creates a resource. For a single instance:

PUT /customers/42 {"name":"John Si",

"countryCode":"US"}
200 OK
Full replacement:
200 OK
OAuth is the preferred approach to authentication because it allows
Creation:
users to decide what level of access the integrating application can
201 OK
have while also being able to set time-based limits. Some APIs have
shorter time limits for which the use of refresh tokens is needed.
PATCH makes partial updates to a resource. For a single instance:

PATCH /customers/42 {"countryCode":"UK"} Open ID Connect is a standardization of OAuth 2.0 that adds a layer
200 OK of normalized third-party identification and user identity. Not all API
providers need it, but it is recommended if you want fine-grained
DELETE deletes any existing resource. For a single instance: authorization controls and manage several identity providers.

Delete /customers/42 WEBHOOKS

204 OK
Webhooks allow you to get updates as they occur in real time, as they
are pull-based instead of push-based. In this method, when updates
AUTHENTICATION occur from the application, they are sent to a URL that you've specified
Getting the right access to the right data underpins any integration for your application to use. This push-based refreshing of information
project, yet authentication can be one of the hardest parts. is what gives applications the ability to update in real time and create
Authentication at its core is the ability to prove your application's dynamic user experiences.
identity. There are several different ways applications can grant access
to developers to create integrations. Additionally, it is the preferred pattern since the implementation is
just a URL, as opposed to polling where you need to create a polling
Follow industry-accepted authentication and identity framework that manages the frequency and scope of the information
PATTERN
protocols, regarding your business needs.
you wish to receive.

API KEYS For example, Marketo's polling framework is 239 lines of code compared

The use of API keys is still pervasive and very common for API access. to just five lines for a similar webhook.

It is a fast, easy way to authenticate accounts and is relatively low

Figure 2: Polling vs. webhooks
overhead for the provider, as the provider can easily create and
purge API keys. API keys are a uniquely generated set of characters,
sometimes random, and are often sent as a pair, a user, and a secret.
When receiving API keys, it's best to copy and store them in a password
manager and treat them like any other password.

OAUTH 2.0 AND OPENID CONNECT

OAuth is a bit different in that it is token-based. There are three
major components in OAuth: the user, the consumer or integrating

REFCARD | MARCH 2022 5 BROUGHT TO YOU IN PARTNERSHIP WITH

 REFCARD | API INTEGR ATION PATTERNS

QUERYING FIRST, LAST, AND COUNT KEY WORDS

Use universally conventional keywords and characters in

Use first, last, and count to get the first item, the last item, and the
PATTERN
your parameters to query, search, and paginate. number of items in a collection:

GET /customers/first
We've automated the movement of data so that our integration is live
200 OK
and fluid, but now it's flowing in like a river when all we really need is
{"name":"John Doe", "status":"VIP"}
a small piece of the data that is useful to what our application is doing.
We need to set query parameters to filter out all the data that we don't GET /customers/last
need. Querying is the last part of the API endpoint, or path, that directs 200 OK
the call to pull only the data you want: {"name":"Johnny Doe", "status":"VIP"}

GET /widgets?query_parameter_here
GET /customers/count
200 OK
The ability to search against databases as well as the target applications {"5"}
is a crucial step. This allows you to test and confirm responses and see
any difference in the data structure between what is returned and what SORTING AND ORDERING
is in the documentation. Querying allows you to modify the key-value An important piece to getting the information you need is how the data
pairs of the request. At the end of the URL path, the query starts with a will be presented at first glance, which becomes especially helpful in
question mark (?) and is separated with an ampersand (&). For example: testing and presenting data through a UI. Many APIs will support sort,
sort_by, or order parameters in the URL to change the ascending
GET /widgets?type=best&date=yesterday
or descending nature of the data you're working with. For example, a
To test an endpoint, there are multiple options depending on which GET /widgets?sort_by=desc(created) can give us the freshest

language you prefer, but the majority of API documentation will widgets in inventory.
reference commands in curl. To test an API, open your Terminal and
PAGINATION
copy/paste the curl command to see what response you get. Now try
adjusting the key-value pairs and fine tune to just the information your Use pagination methods for web front ends and
PATTERN
mobile usage.
application needs from the target endpoint. When adding parameters
to a curl command directly, be sure to include a backslash (/) before
Pagination requires some implied order by a field, or fields, like unique
the question mark of the query as ? and & are special characters.
id, created date, and modified date. There are a few different types of
Tweaking these pairs will decrease the size and overhead your
pagination you can implement based on your needs.
application might expect. You can always increase the amount of data
— especially in testing — to see where you might run into errors.
PARTIAL RESPONSE
In some cases, you don't need to get all fields that define your object.
FILTERS
Partial responses are especially useful in mobile use cases, for example,
To filter, you must use ? to filter resources and use & as separator
where bandwidth optimization is a priority. Use the fields keyword to
between parameters:
get the specific fields you want:
GET /widgets?type=best&date=yesterday
GET /customers/42?fields=name,status
200 OK
SEARCH
{"name":"John Doe", "status":"VIP"
Using the way Google Search works (i.e., with the search keyword) is
}
often the preferred pattern for searching resources — for example,
when you search the word test: www.google.com/search?q=test.
OFFSET
To search a specific resource: This is easiest to implement and is therefore very common. The
LIMIT is the number of rows that will be returned, and OFFSET is the
GET /customers/search?type=vip
starting point of results. For example, a path of /widgets?limit=10
would return 10 rows for the first page. Then the second page could be
To search multiple resources:
/widgets?limit=10&offset=10, which would return 10 rows,
GET /search?q=customers+vip starting with the 10th row, and so on.

REFCARD | MARCH 2022 6 BROUGHT TO YOU IN PARTNERSHIP WITH

 REFCARD | API INTEGR ATION PATTERNS

The downside of using offset pagination is it becomes less performant Figure 3: Bulk data transfer
with large data sets. For example, if the offset is 1M rows, it will still have
to run through 1M rows before returning the limit requested.

KEYSET
A keyset is helpful to get around large data sets and uses the filter
value of the last page of results as the starting point for the next page
of results using an additional limit URL parameter. For example, the
first call could be GET /widgets?limit=10 with either a unique
identifier such as date created or modified. The second call would be
GET /widgets?limit=10&created:lte:2019-09, the next would be
GET /widgets?limit=10&created:lte:2019-10, and so on.

FIXED DATA PAGES

Fairly straightforward, when adding into the query, you select which
page of data you would like returned. For example, to return the fourth
SDKS
page of results, you would use this query: GET /widgets?page=4.
This method is preferred if the application you're integrating with PATTERN Propose an SDK to help developers to use your API.
has known pages and you would like the data returned sequentially.
However, it becomes harder if you're not sure what exactly is on that Many API providers offer SDKs to help users easily integrate them,
fourth page. which includes setting up the API's interface, methods, error handling,
access security, etc. Users have to manage the changes in their code as
FLEXIBLE DATA PAGES the API is modified; therefore, it is crucial that an SDK updates at the
Similar to fixed data pages, you could still call the fourth page same rate as the API itself — not to mention the support for version
of widgets, but now you can specify the size of the page. Calling upgrades, debugging, and developer errors.
GET /widgets?page=4&page_size=25 allows you to further dictate
what you will get back in terms of page size. This can be very helpful if An SDK also allows you to encrypt data and strengthen security

you're building a UI and need the results to be a certain size. requirements (e.g., for storing passwords). For the medical and
financial sectors in particular, SDKs can help enforce user compliance
BULK with relevant regulations.

PATTERN Use bulk data transfer for large volumes of data.

Below are several practices for developing an SDK:

•  Mutualize in the form of a batch in the same HTTP call as

Up to this point, API integration has focused on specific sets of data,
much as possible because the opening of sessions and
but what happens when you need to move a large amount of data from
connections is very consuming. You can set up a queuing
one system to another? Some applications expose this ability with Bulk
system for when the calls do not necessarily need to be
APIs. Bulk APIs allow you to update, insert, and delete a large number
received at the same time.
of records all at once. This can be particularly useful when transferring
large systems of record (e.g., marketing automation, CRM, or ERP) from •  Compress payload; it can be easy to forget this when calling
one provider to another. an API — you might as well not forget it in the SDK.

•  Fill in the User-Agent header with the SDK version number

Bulk operates in several batches of data sets when a request for a bulk
and the SDK language, which will provide information on the
job is sent to the application provider. The application provider will
adoption of new versions of your SDK.
send batches over asynchronously to complete the job. Depending on
the size of the data set, the job will also send you a unique identifier to •  Set up API analytics to measure usage and performance and
check the job status and close the job once complete. to see what improvements could be made to the SDK.

•  Offer the most popular languages, especially those that the

Be sure to double-check the file type that a bulk API will provide —
API's target developers use the most.
either CSV, JSON, or XML. Additionally, if you're not getting the full data
set back, be sure to check any API rate limits that apply, as you may •  Document the SDK comprehensively, with a complete
exceed them with large data transfers. changelog, but also for its parameterization.

REFCARD | MARCH 2022 7 BROUGHT TO YOU IN PARTNERSHIP WITH

 REFCARD | API INTEGR ATION PATTERNS

ADDITIONAL RESOURCES
•  Richardson, L. & Amundsen, M. (2015). RESTful Web APIs. WRITTEN BY THOMAS JARDINET,
IT ARCHITECT AT MANPOWER
O'Reilly.
As an IT architect with seventeen years of
•  Biehl, M. (2016). RESTful API Design. CreateSpace.
experience, I oversee business projects by defining
their architectures, whether functional, applicational,
•  Louvel, J. (2013). Restlet in Action: Developing RESTful Web
or technical, studying the best path forward. As a supporter
APIs in Java. Manning. of flattened organizations, I also accompany them on the
organizational side, and above all, I seek both an intellectual and
•  Kalali, M. & Mehta, B. (2013). Developing RESTful Services With human exchange.
JAX-RS 2.0, WebSockets, and JSON. Packt Publishing.

•  Jacobson, D., Brail, G. & Woods, D. (2011). APIs: A Strategy

Guide. O'Reilly. 600 Park Offices Drive, Suite 300
Research Triangle Park, NC 27709
888.678.0399 | 919.678.0300
•  Lauret, A. (2019). The Design of Web APIs. Manning.
At DZone, we foster a collaborative environment that empowers developers and
•  Higginbotham, J. (2021). Principles of Web API Design: tech professionals to share knowledge, build skills, and solve problems through
Delivering Value With APIs and Microservices. Addison- content, code, and community. We thoughtfully — and with intention — challenge
the status quo and value diverse perspectives so that, as one, we can inspire
Wesley Professional. positive change through technology.

Copyright © 2022 DZone, Inc. All rights reserved. No part of this publication
may be reproduced, stored in a retrieval system, or transmitted, in any form or
by means of electronic, mechanical, photocopying, or otherwise, without prior
written permission of the publisher.

REFCARD | MARCH 2022 8 BROUGHT TO YOU IN PARTNERSHIP WITH