EBOOK

The 4 secrets
of a great API
Deliver successful APIs with
these insider secrets
Too many application programming
interface (API) providers build their APIs
before thinking through critical success
factors, resulting in downstream hurdles
and unmet business needs. But, by
following a few proven principles, you
can deliver top-quality APIs without the
headaches. Here are four insider secrets
to building APIs that drive performance:
 01

Secret #1:

T H E 4 S E C R E T S O F A G R E AT A P I
Design for user experience

To deliver exceptional APIs, design must be the first priority. Just as

optimizing for user experience (UX) has become a primary concern in
user interaction (UI) development, optimizing for API user experience
(APX) should be a primary concern in API development.

An optimal API design helps application of an API while rendering in real time an
developers understand the purpose interactive console to enable interaction
and functionality of the API so they can with it. As the API is designed, application
quickly become productive using it. It developers can test its behavior with an

3
allows organizations to focus on getting
the API design right and avoid expensive “An optimal API design helps
and time-consuming mistakes in back-end application developers understand
implementation.
the purpose and functionality of
The best method for designing an API that
the API so they can quickly become
developers want to use is to iteratively productive using it.”
define the structure of the API in an
expressive manner, inviting feedback from integrated mocking service that returns
developers along the way. The API designer the same values that a call to the live API
is an example of this concept in action. would produce. Because APIs designed in
Using an open-source design environment RAML are concise and easy to understand,
that leverages RAML® — the RESTful API application developers can rapidly assess an
©2021 M U L E S O F T ­­— M U L E S O F T . C O M

Modeling Language — the API designer API’s functionality and usability, and offer
provides an editor for drafting the structure concrete improvement tips.
 02

Secret #2:

T H E 4 S E C R E T S O F A G R E AT A P I
Optimize for the use case

There is no such thing as a one-size-fits-all API. Even for the same

underlying service or set of services, multiple APIs may be required
to support different types of users and use cases. An API should be
optimized to fulfill a specific business request in a specific context.

Too often, APIs are modeled after the design Keep in mind that this use case is granular.
of the back-end services or applications The API will look up an order based on
they expose instead of the use case they the order number and return a status.
fulfill. This results in poor performance of Therefore, the API should expose this

4
the client application, poor user experience,
and, ultimately, poor adoption. “If you’re designing an API to
enable access to sales order
To optimize your API for a specific use case,
statuses from a mobile device, you
consider how coarse- or fine-grained it
should be. For example, if you’re designing
must acknowledge the constraints
an API to enable access to sales order of a mobile application.”
statuses from a mobile device, you must
acknowledge the constraints of a mobile specific fine-grained functionality so it can
application: higher sensitivity to the number be invoked independently. If the underlying
of network trips, latency, and data size than service it accesses is coarse-grained and you
a web application. Accordingly, this API anticipate building additional APIs on that
should be designed to limit back-end calls service to address other use cases, consider
©2021 M U L E S O F T ­­— M U L E S O F T . C O M

and minimize the size of data returned. a tiered approach.

 03

Secret #3:

T H E 4 S E C R E T S O F A G R E AT A P I
Provide easy access

Finding an audience for your API begins with publishing it to a

portal that allows developers to discover and evaluate it for their use
case. The developer portal should include all the context and tools
developers need to learn about and begin using your API.

Assume that developers reviewing your of the value-added features that make
API will only invest a few minutes before it simple for application developers to
deciding whether or not to consider it. Make engage with an API. The API portal includes
information about your API available in a interactive documentation that not only

5
clear and easy-to-consume format so that
developers can scan your documentation “Make information about your
quickly, get an overview of the API API available in a clear and
functionality, and comfortably understand
easy-to-consume format so
how much effort it will take for them to get
it up and running. From there, they’ll want
that developers can scan your
to see some examples, so be prepared to documentation quickly.”
include at least one or two. Avoid static
documentation pages — developers are far describes the endpoint, but also the fields
more likely to use an API if they can interact required to call that API and the data that
with it as they learn about it. is returned. Additionally, you can add code
samples, giving developers a head start in
The API portal delivered in MuleSoft’s building the code to access your API in the
©2021 M U L E S O F T ­­— M U L E S O F T . C O M

Anypoint Platform™ is a good example applications they create.

 04

Secret #4:

T H E 4 S E C R E T S O F A G R E AT A P I
Build a community

The application developers who consume your API are not just your
customers — they are the ecosystem that will drive the success of your
API. By treating them as valued members of your community, you
cultivate a thriving developer network that will not only offer a wider
reach for what you’ve built, but also ensure its quality.

To support the organic growth of your API, you can use to enhance your API over
your developer portal should include an time. As new versions of your API are
easy way for developers to share knowledge. released, you can easily communicate the

6
The API Notebook of the API portal does enhancements through the developer
precisely that. It allows developers to
discover and document new uses for your “To support the organic growth of
API, growing the addressable market for it, your API, your developer portal
providing forums where they can share tips
should include an easy way for
and code samples, and making it easier for
others to get started with your API. developers to share knowledge.”

Your API is not a static entity. As new use portal. Plus, you can quickly assess who is
cases are identified and use of your API using each version of your API and relay
expands, enhancements and fixes are an upgrade path as you deprecate older
inevitable. The greater the number of versions.
developers using your API, the faster bugs
©2021 M U L E S O F T ­­— M U L E S O F T . C O M

and issues will be identified. By treating your developer community as an

extension of your business, you’ll create not
Understanding your developer community only great APIs, but also the flexible, resilient
and having accurate insight into use cases connections needed to speed up processes
and patterns will provide vital knowledge and make way for innovation at every level.
These four secrets can help
organizations create APIs that users find
valuable and engaging. By designing
your API with an outside-in mindset
— prioritizing users and the business
processes the API will support — you
encourage developers to both leverage
and actively participate in improving
your API.

To learn more about accelerating innovation and

optimizing efficiency in your organization, listen to
the Secrets of a great API webinar.
MULESOFT, A SALESFORCE COMPANY

MuleSoft, the world’s #1 integration and API platform, makes it easy to connect data from any system
— no matter where it resides — to create connected experiences, faster. Thousands of organizations
across industries rely on MuleSoft to realize speed, agility, and innovation at scale. By integrating
systems and unifying data with reusable APIs, businesses can easily compose connected experiences
while maintaining security and control. Through API-led connectivity, customers unlock business
capabilities to build application networks that deliver exponentially increasing value. MuleSoft is the
only unified platform for enterprise iPaaS and full lifecycle API management, and can be deployed to
any cloud or on-premises with a single runtime.

MULESOFT IS A TRADEMARK OF MULESOFT, LLC., A SALESFORCE COMPANY.