Be My API How to Implement an API Strategy Everyone will Love

1

Be My API <3 How to implement an API strategy everyone will love.

Mike Amundsen

Principal API Architect

Layer 7 Technologies

@mamund

2

PRELIMINARIES

3

Mike Amundsen

Author, Web Architect, Presenter

Principal API Architect

Hypermedia Junkie

Building Hypermedia APIs with HTML5 and Node

RESTful Web APIs (w/ Leonard Richardson)

4

API Academy

Mike Amundsen Ronnie Mitra Alex Gaber

5

API Academy

http://forms.layer7tech.com/FW-API13

6

API Academy

7

API Academy Web Site (URI shortly)

8

Housekeeping

Questions

- Post questions to Q&A, we’ll cover them at breaks throughout the sessions

Twitter

- Today’s event hashtag:

- #L7webinar

- Follow us on Twitter:

- @layer7

- @mamund (Mike Amundsen)

- @intalex (Alex Gaber)

- @mitraman (Ronnie Mitra)

facebook.com/layer7

layer7.com/blogs

layer7.com/linkedin

9

Outline

The Business of APIs

The USE methodology (Usable, Scalable, Evolvable)

Implementing a Solid Foundation

API Interaction Models

10

THE BUSINESS OF APIS

11

The Business of APIs

API Consumers

Acquisition Targets

Product Models

12

API Consumer: Private

Internal/contract developers

Implementation control

Your product is understood

Your control is the code/deployment

Agenda alignment

Private APIs offer the ability to strengthen

your market

13

API Consumer: Partner

Strategic Partners

Limited implementation control

Your product is your SDK

Your control is access internal content, users, etc.

Agenda Co-operation

Partner APIs offer opportunities to

extend your market

14

API Consumer: Public

“Third-party” developers

Little to no implementation control

Your product is your API

Your control is the API

Agenda wide open

Public APIs offer a chance to discover

new markets

15

API Consumer

Private APIs to strengthen your market

Partner APIs to extend your market

Public APIs to discover new markets

16

Acquisition: Reach

Increase install base

Enter new markets

Raise awareness/presence

Leverage existing products

17

Acquisition: Content

Increase contributed user content

Gather behavioral data

Make new content connections

Build upon existing infrastructure

18

Acquisition: Users

Expand user base

Increase user traffic

Increase user data

Deepen customer relationships

19

Acquisition

Leverage existing products

Build upon existing infrastructure

Deepen customer relationships

20

Product: Monitor

Know your product

What APIs are used?

Who is using them?

When they are using them?

You are your best source of “big data”

21

Product: Measure

What are your metrics?

API performance

- Latency

- Uptime

- Reliability

Dev performance

- “Installs”

- Traffic

- Stability

You can’t improve what you don’t measure

22

Product: Modify

Small changes can mean big results

Use your APIs to test new ideas, new products

“CI” means constant improvement

Turn feedback into features

23

Product

You are your best source of “big data”

You can’t improve what you don’t measure

Turn feedback into features

24

The Business of APIs

API Consumers

- Private, Partner, Public

Acquisition Target

- Reach, Content, Users

Product Modeling

- Monitor, Measure, Modify

25

USABLE, SCALABLE,

EVOLVABLE (USE)

26

Usable

“Usability is the ease of use and learnability of a human-made object.”

27

Usable

“Usability is the ease of use and learnability of a human-made object.”

In API, the “I” stands for “Interface”

How usable is your interface?

Design for Usability

- Early focus on users and tasks

- Empirical measurement

- Iterative design

Be prepared to measure and iterate

28

Scalable

“Scalability is the ability of a system, network, or process, to handle a growing

amount of work in a capable manner …”

29

Scalable

“Scalability is the ability of a system, network, or process, to handle a growing

amount of work in a capable manner …”

Scaling out vs. scaling up

Scaling up (more memory, etc.) is “easier” and more limiting

Scaling out (more machines) is “harder” and more reliable over time

Design-in support for the

“Layered Constraint” (Fielding’s REST)

Take advantage of “DevOps” practices to

support scaling

Be prepared to scale out

30

Evolvable

“Evolvability is defined as the capacity of a system for adaptive evolution.”

31

Evolvable

“Evolvability is defined as the capacity of a system for adaptive evolution.”

Extend (pandere or “to stretch”)

- Existing elements cannot be removed

- Meaning/processing of existing elements cannot be changed

- New elements must be optional

Versioning (vertere or “to turn”)

- Make it easy to identfy the “version”

- Implementations should reject unsupported

versions

Don’t version unless it is unavoidable

Be prepared for clients to ignore version details

Do not create “Dodo” apps.

32

Review

Usable

- Your API is your Interface

- Focus on users & tasks, measure, iterate

Scable

- Scaling out is the key

- Take advantage of DevOps practices

Evolvable

- Don’t create Dodo apps

- Favor extending over versioning whenever possible

33

IMPLEMENT A SOLID

FOUNDATION

34

Component != Connector

35

Component

Database

File System

Message Queue

Transaction Manager

Source Code

36

Component == Private

37

38

Connector

Web Server

Browser Agent

Proxy Server

Shared Cache

39

Connector == Public

40

41

Client Server Connectors

Components

The Web

42

Representation Layer

43

Representation Layer

Representation happens in the Connector

HTTP supports content negotiation

- Accept

- Content-Type

Differing clients (user-agents) === differing representations

- Desktop

- Browser

- Tablet

- Smartphone

Be prepared to support multiple representations

44

Caching Layer

45

Caching Layer

Caching happens EVERYWHERE

HTTP supports Expiration Model and Validation Model Caching

Expiration Model

- Expires

- Cache-Control: max-age

Validation Model

- Last-Modified

- Etag, If-Match

Be prepared to support caching for both client and server

Squid, Varnish, Nginx, MemCacheD, etc.

46

Security Layer

47

Security Layer

Security happens at the edges

HTTP supports authentication negotiation

- WWW-Authenticate

- Authorization

- Proxy versions, too

Keep Authentication out of your components

Perform Authorization as early as possible

Various security/routing proxies available

48

Review

Components != Connectors

- Components are private (DB Server)

- Connectors are public (HTTP)

Representation Layer

- You only send representations

- Be prepared to support multiple representation formats

Caching Layer

- Caching happens everywhere

- Support caching at client and server (proxies)

Security Layer

- Security happens at the edges

- Use security proxies for better compliance/performance

49

THE API INTERACTION MODEL

50

Interaction Model as a Implementation Strategy

Lots of things to decide when creating an implementation

How do we make good choices?

What is our “basis” for decisions?

51

Lots of Choices

SOAP, CRUD, REST

XML, JSON, HTML

Caching

Security

Error Formats, etc.

52

Focus on Interactions, not technologies

Great APIs are based on interactions

Great design starts with the user perspective

Focus on how the API will be used, not what it exposes

Let’s apply UX (user experience) concepts to DX (developer experience)

53

Three Questions

Who will use this API?

What will it be used to create?

How will the API actually behave?

54

API Interaction Actors

Developer

Application

End User

55

API Usage Scenarios

Focus on Activities, not Objects

How will this API help the developer?

Narrow the interface to those things you want to encourage.

56

Interface Behavior

Build a model of tasks

Identify data points needed to complete the tasks

Map out interaction details for each task (or set of tasks)

57

Some Tips

Be sure to include error-handling interactions

- Is this Fixable?

- Repeatable?

- Safe/Unsafe?

Keep it “abstract”

- Don’t get tied up w/ technology (formats, libraries, frameworks, etc.)

- Describe your model independent of protocol (HTTP, webSockets, etc.)

- Maintain your DX perspective at all times.

58

Review

Focus on interactions, not technologies

Maintain the developer perspective

Tasks -> Data -> Models

Keep it “abstract”

59

SUMMARY

60

The Business of APIs

API Consumers

- Private, Partner, Public

Acquisition Target

- Reach, Content, Users

Product Modeling

- Monitor, Measure, Modify

61

Usable, Scalable, Evolvable (USE)

Usable

- Your API is your Interface

- Focus on users & tasks, measure, iterate

Scable

- Scaling out is the key

- Take advantage of DevOps practices

Evolvable

- Don’t create Dodo apps

- Favor extending over versioning whenever possible

62

Implement a Solid Foundation

Components != Connectors

- Components are private (DB Server)

- Connectors are public (HTTP)

Representation Layer

- You only send representations

- Be prepared to support multiple representation formats

Caching Layer

- Caching happens everywhere

- Support caching at client and server (proxies)

Security Layer

- Security happens at the edges

- Use security proxies for better compliance/performance

63

API Interaction Models

Focus on interactions, not technologies

Maintain the developer perspective

Tasks -> Data -> Models

Keep it “abstract”

64

In Conclusion

The Business of APIs

The USE methodology (Usable, Scalable, Evolvable)

Implementing a Solid Foundation

API Interaction Models

65

Thank you

Twitter

- Today’s event hashtag:

- #L7webinar

- Follow us on Twitter:

- @layer7

- @mamund (Mike Amundsen)

- @intalex (Alex Gaber)

- @mitraman (Ronnie Mitra)

facebook.com/layer7

layer7.com/blogs

layer7.com/linkedin

66

Mike Amundsen

Principal API Architect

Layer 7 Technologies

@mamund

Be My API <3 How to implement an API strategy everyone will love.