Designing Usable APIs featuring Forrester Research, Inc

Designing Usable APIs

Ronnie Mitra Randy Heffner

@mitraman @biztech21

[email protected] [email protected]

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

Webinar Housekeeping

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

Allow customers to directly manipulate account and

order information

(Saxo Bank, Optify)

Customer service

Create end-to-end monitored process flow across

customers and partners

(Con-Way Freight)

Process optimization

Provide useful data that people can build into

consumer-facing apps

(USA Today, Yellow Pages)

Market mindshare

Build volume by letting others sell your products as their

own

(Travelocity, Expedia)

White-label your business

Let partners seamlessly embed your business into

their offerings

(Amazon store, Sears)

Channel enablement

© 2013 Forrester Research, Inc. Reproduction Prohibited 6

Strong API design: Five major areas

• Based on business context of API use and design API categories

• Function, purpose, architecture context API types

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

Interface technical design

• Effect of API limits, testing, support Community concerns

• Open-ended design, portfolio management

Future preparation

Business context sets API category

Open web APIs

Tech-savvy consumers

B2B APIs

Internal APIs

Product APIs

Value-add innovators

Digital disruptors

Suppliers Distribution

partners

Digital experiences (mobile, web, etc.)

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

Products (software,

physical products, services)

Enterprise customers

Web site developers

Your enterprise Your products

Tech-savvy consumers

Product ecosystem

Wide-open to innovation Optimized business Build product ecosystems

Enterprise customers

1 2

3

4


Purpose and function drive API types

• Play in the data economy

• Direct entity/collection access Data APIs

• Complex, multiple resource interactions

• Push processes forward Transaction APIs

• Technical connections between siloed applications Integration APIs

• Serve UI fragments and fully-formed UI components User interface APIs

• Provide business function support Application

component APIs

• Technical support, such as security, logging, and format conversion Utility APIs

Mobile needs multiple API types

Device

UI-level APIs

Core SOA business transactions

UI logic

API façade for core transactions

Mobile backend

Core systems

Local / cached data

UI

Local / cached data User

interface APIs

Data APIs

Trans-action APIs

18%

14%

19%

15%

8%

6%

26%

27%

15%

18%

16%

11%

7%

7%

4%

4%

6%

4%

25%

26%

30%

33%

40%

40%

1%

1%

3%

1%

3%

1%

23%

25%

30%

29%

27%

38%

Service-oriented architecture

APIs exposed internally

SOAP-based services

Message-oriented middleware

APIs exposed externally

RESTful services

Implemented, not expanding Implemented, expanding Planning to implement

No plans Decreasing or removing Don't know/N/A

REST vs SOAP: Watch out for religion

Source: Forrsights Developer Survey, Q1 2013

Which of the following architecture styles does your organization

currently use or plan to use?

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

Net expansion

audience

15%

19%

21%

16%

33%

33%

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

• UI development (Twitter Embedded Timeline) JavaScript APIs

• Natural programming constructs

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

Language bindings (i.e., SDKs)

• Good for periodic info distribution RSS and Atom

• Good for continuous info distribution (E*Trade) Streaming API

• XMPP for bioinformatics

• Ford OpenXC USB, Bluetooth Special cases

REST: Design for comprehensibility

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

domain name encryption URI path query string

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 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 | XML | XHTML | ZIP | others

no links | links as HTML relations | links as payload data | others

Payload:

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

No links: Simplest for reach to a broad audience

<rel>: Provides for parsing for a specific link type

In-payload: Greater programming flexibility

REST verbs: Not as clear as you think

GET | POST | PUT | DELETE | HEAD | OPTIONS | PATCH HTTP verb:

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

• Simplest, but must have Internet address

• Separate calls for each attachment URI reference

• Single request

• Larger message size

• Nontrivial for API users and providers

Binary in the payload

• Clarity on media types

• Separate calls for each attachment

• No place for metadata upon retrieval

Separate attachment API

• Single request; best efficiency

• More difficult to program

Multipart messages

One way or the other, plan for versioning

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

Early, for API “family” management

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

https://api.mycompany.com/name-of-api-request?version=2 URI:

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/. . .

Late, for API independence

Query string, to make it optional – Danger Zone


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


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

Thank you

Randy Heffner

[email protected]

@BizTech21

Ronnie Mitra

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

2. Design URIs

3. Define operations

bushels

/bushel/apples

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

Negative Feelings

Confusion Mistrust

Isolation Anger

Embarrassment Abandonment

Frustration Neglected

Partner API DX

Positive Feelings

Safety Trust

Empowerment Amazement

Eagerness Pride

Familiarity Inspired

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

API

Delivering a Developer Experience

Developer

Portal


API Gateway


API Gateway

Developer Portal

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 Randy Heffner

@mitraman @biztech21

[email protected] [email protected]

Technology

Designing Usable APIs featuring Forrester Research, Inc