Designing Usable APIs featuring Forrester Research, Inc.

Designing Usable APIs
Ronnie Mitra
@mitraman
rmitra@layer7tech.com

Randy Heffner
@biztech21
rheffner@forrester.com

Webinar Housekeeping
Questions

-Chat any questions you have and we’ll answer them at the
end of this webinar
Twitter
- Today’s event hashtag: #L7webinar

Follow us on Twitter:
@layer7
@mitraman
@forrester
@biztech21

The Keys To Well-Designed APIs
Randy Heffner, Vice President & Principal Analyst
November 6, 2013

Enterprises are deep into APIs

Sample business goals for external APIs
Customer
service

Process
optimization

Allow customers to directly
manipulate account and
order information
(Saxo Bank, Optify)

Create end-to-end monitored
process flow across
customers and partners
(Con-Way Freight)

Market
mindshare

Channel
enablement

Let partners seamlessly
embed your business into
their offerings
(Amazon store, Sears)

Provide useful data that
people can build into
consumer-facing apps
(USA Today, Yellow Pages)

White-label
your business

Build volume by letting others
sell your products as their
own
(Travelocity, Expedia)

Strong API design: Five major areas
API categories

• Based on business context of API use
and design

API types

• Function, purpose, architecture context

Interface
technical design

• Messaging style, request structure,
payloads, quality of service

Community
concerns

• Effect of API limits, testing, support

Future
preparation

• Open-ended design, portfolio
management

© 2013 Forrester Research, Inc. Reproduction Prohibited

6

Business context sets API category
Wide-open to innovation
Tech-savvy
consumers

Web site
developers

Value-add
innovators

Digital
disruptors

Digital experiences
(mobile, web, etc.)

Optimized business

Build product ecosystems

Enterprise
customers
Distribution
partners

1

Enterprise
customers

Suppliers

2

Open web APIs

Tech-savvy
consumers

Product
ecosystem

4

B2B APIs

Product APIs
Products

3

Internal APIs

(software,
physical products,
services)

Enterprise applications
(custom, off-the-shelf, cloud, on-premise)

Your enterprise

Your products

Purpose and function drive API types
Data APIs

• Play in the data economy
• Direct entity/collection access

Transaction APIs

• Complex, multiple resource interactions
• Push processes forward

Integration APIs

• Technical connections between siloed
applications

User interface APIs

Application
component APIs
Utility APIs


• Serve UI fragments and fully-formed UI
components
• Provide business function support
• Technical support, such as security,
logging, and format conversion

8

Mobile needs multiple API types
UI

User
interface
APIs

Local / cached data

Device
UI-level APIs

Data
APIs

API façade for core
transactions

UI logic

Mobile backend

Transaction
APIs

Local / cached data

Core SOA business transactions

Core systems

REST vs SOAP: Watch out for religion
Which of the following architecture styles does your organization
currently use or plan to use?
Implemented, not expanding
No plans

Implemented, expanding
Decreasing or removing

Service-oriented architecture
APIs exposed internally

18%

26%

14%

SOAP-based services
Message-oriented middleware

19%
15%

Planning to implement
Don't know/N/A

7%

27%

7%

25% 1% 23%
26%

1% 25%

Net expansion
audience
33%
33%

15% 4%

30%

3%

30%

16%

18%

33%

1%

29%

21%

3%

27%

19%

APIs exposed externally 8% 16%

6%

RESTful services 6%11% 4%

4%

40%
40%

1%

38%

15%

Note: Net expansion audience = “implemented, expanding” + “planning to implement” – “decreasing or removing”
Base: 368 Professional Developers, IT Developers, Consultants that work for organizations with 1,000+ employees
Source: Forrsights Developer Survey, Q1 2013

Messaging types vary on reach, QoS
Messaging type

Reach

Quality of service (QoS)

Free-form REST

Any API category; especially
important for open Web

Custom configuration of open
standards; validation limited with
JSON

Free-form REST
with hypermedia

Any API category; higher
skill requirement limits
audience

Custom configuration of open
standards; validation limited with
JSON

Structured REST
(e.g., OData)

May need to hide formal
structure to gain broad reach

Standardized patterns based on
open standards; defined types
support validation of JSON

SOAP

Internal APIs; some B2B
APIs; very few open Web
APIs

Strong validation, standards for
security, federation, reliable
messaging, and attachments

Message-oriented
(e.g., JMS)

Internal APIs; very limited
B2B APIs

Transactional messaging;
validation with XML payload

Alternate API types fit special contexts
JavaScript APIs

• UI development (Twitter Embedded Timeline)

Language bindings
(i.e., SDKs)

• Natural programming constructs
• Can layer on top of API-based services (Box)

RSS and Atom

• Good for periodic info distribution

Streaming API

• Good for continuous info distribution (E*Trade)

Special cases

• XMPP for bioinformatics
• Ford OpenXC  USB, Bluetooth


12

REST: Design for comprehensibility
Encryption
With open HTTP, assume that credentials will be stolen
Domain name
Keep domain names stable; may be useful for grouping
or macro-level routing

URI: https://api.mycompany.com/name-of-api-request?parameter=abc
encryption

domain name

URI path

query string

URI path
Resources are all the rage, but functions (actions) are
sometimes more clear, direct, and comprehensible;
additional path nodes may add clarity through structure
Query string
Allow simple, straightforward options, but don’t use it to
introduce whole new API functions

Simple if can be, complex if need be
JSON: Fast becoming preferred on the open Web
XML: Benefits for validation and vertical industries
XHTML: Benefits for validation and web app support
Zip: Smaller payloads; less reach

Payload: JSON | XML | XHTML | ZIP | others
no links | links as HTML relations | links as payload data | others
In-payload: Greater programming flexibility

<rel>: Provides for parsing for a specific link type
No links: Simplest for reach to a broad audience

REST verbs: Not as clear as you think
HTTP verb: GET | POST | PUT | DELETE | HEAD | OPTIONS | PATCH

Q: Which is the correct handling of “POST /order”?
A) Store a new order record — AND submit the order for processing
B) Store a new order record — DO NOT submit the order for processing
C) Store a new order record — DO submit IF orderStatus = “submit”
D) Store a new order record ONLY if it passes validation

A: Whatever it says in the documentation

The lesson:
REST is clear only in your documentation

REST attachments: No easy way
URI reference

• Simplest, but must have Internet address
• Separate calls for each attachment

Binary in the
payload

• Single request
• Larger message size
• Nontrivial for API users and providers

Separate
attachment API

• Clarity on media types
• Separate calls for each attachment
• No place for metadata upon retrieval

Multipart
messages

• Single request; best efficiency
• More difficult to program
16

One way or the other, plan for versioning
URI: https://api.mycompany.com/v2/name-of-api-request?parameter=abc
Early, for API “family” management

URI: https://api.mycompany.com/name-of-api-request/v2?parameter=abc
Late, for API independence

URI: https://api.mycompany.com/name-of-api-request?version=2
Query string, to make it optional – Danger Zone

Gotta have a good reason:
In the domain name: https://apiV1.mycompany.com/. . .
As a custom media type: application/x-customerV1

In the request payload: {

“version": “v1", . . . }

As an HTTP port number: https://api.mycompany.com:49152/. . .

API security: Know your scenarios
Scenario

Top approaches

Open Web partnering
You own the data and want to
expand market presence

• API key
• Digital signature

Open Web customer integration
Customers own the data

• API key
• OAuth

B2B process APIs
You and/or partners own the data

• Two-way SSL
• Federated identity (SAML, OpenID
Connect)

B2B service provider APIs
Your partners’ or customers’
stakeholders own the data

• OAuth
• Federated identity
• Two-way SSL

Internal APIs
You alone handle the data

• Wide latitude
• SOA security as strong foundation


18

API design recommendations

› Start with your business purpose and audience
› Favor REST for external reach; don’t fear SOAP
› With REST, assume nothing in your docs
› Decide how open-ended to be:
• Data (resource) APIs support an open-ended future
• Transaction (function or action) APIs provide better
protection for business integrity
• Query parameters enable special functions


19

Thank you
Randy Heffner
@BizTech21

API Program Challenges
Big Questions:
- How do we align with strategic goals?
- What should the API look like?
- What message formats ? Which style? What protocol?
- What API style?

?

How do you design an API?

1. Identify resources

bushels

2. Design URIs

/bushel/apples

3. Define operations

GET

apples

/bushel/apples

This is not enough!

What is Developer Experience (DX)?
 Developers are the users of an API
 User Experience (UX) for an API = Developer Experience (DX)
 The DX is a measure of how the API makes developers feel

Partner API DX
Positive Feelings
Safety

Trust

Empowerment

Amazement

Eagerness

Pride

Familiarity

Inspired

Negative Feelings
Confusion

Mistrust

Isolation

Anger

Embarrassment

Abandonment

Frustration

Neglected

A DX Focus Aligns with Strategic Goals

Increased Growth

• Market Differentiation
• Increased “stickiness”
• Word of mouth advertising

Reduced Cost

• Reduced learning curve
• Harder to make mistakes
• Better engagement level

Driving Positive Experiences
Category

Examples and Measures

Learning

Appropriate documentation, “hackability”

Engagement

Ease of discovery, ease of registration

Familiarity

API styles, message formats and convention

Suitability

Number of calls required, size of developer stack, latency

Aesthetics

Appropriate presentation, technology choices

Security

Pragmatic controls

Who are your Developer Users?
Platforms
Mobile, web, .net, J2EE
Programming Languages
iOS, Java, HTML, Node, C++, C#
Organization Types
Startup, Enterprise, Hobbyist
Industry / System Knowledge
Expert, Outsider
Years of Experience
Beginner, Expert

The developer is not always right!
 Blindly following users can get designers into trouble
 Observe what developers implement rather than just what they say
 Organizations must balance developer interests with their own

Do it this
way!

Security vs. Usability
 Security can be a competing concern with usability
 The absence of any security may lead to negative feelings (e.g. mistrust, fear)
 Implement “just enough” security

Moving Towards a DX Based Design
Identify Business
Goals

Identify Developer
Audience

Define Interactions

Design API

Three Steps Towards a Better DX
1. Write client code
2. Prototype your API

3. Find a developer

Delivering a Developer Experience

API


Developer
Portal


API Gateway

Developer Portal

API Gateway

API

Summary
 Make rational choices when designing an API
 Use a positive DX as your target
 Don’t underestimate the importance of usability

Questions?

Ronnie Mitra
@mitraman
rmitra@layer7tech.com

Randy Heffner
@biztech21

Designing Usable APIs featuring Forrester Research, Inc.

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Destaque

Destaque (6)

Semelhante a Designing Usable APIs featuring Forrester Research, Inc.

Semelhante a Designing Usable APIs featuring Forrester Research, Inc. (20)

Mais de CA API Management

Mais de CA API Management (20)

Último

Último (20)

Designing Usable APIs featuring Forrester Research, Inc.