Lessons From The Battlefield

Understand the maturity of design and delivery of an API and be open about its state

Define a contract: having an API in place takes consumer website to market without destabilizing the enterprise back-end

1  

If the API is good enough, ship it. The layer Cake, APIs on APIS, is good! Problem with code-first approach: Use APIs to decouple systems rather than expose internal systems.

2  3  

Let’s Talk

APX Application Programming eXperience

Now? In the Future?

Don’t fall prey to paralysis! Limit pool of customers

Commonality is good in API BUT Shoehorning is not!

Who Is Your Customer?

Orchestrating Service Provider OR

What Is Your Value Add?

Core Single-Purpose Service

Front End Think Consumer Experience

Back End Think business processes

Looking Backwards Straight-through Proxy: Abstract Way of Expressing Domain Model Behind You

Looking Forward New Facade: Create a new service based upon capabilities behind you

OR

OR

Think APX

3 Critical Principles To Remember

This is a long-lived interface Expose the interface you want your clients to develop a dependency on.

1

Three Critical Principles of APX

Don’t Expose Dirty Laundry Don’t simply reflect your back end model. Instead, come up with simple, long-lasting domain model.

2

Three Critical Principles of APX

Craft API for your users What will they love? If your API is really good, your users will get attached to it.

3

Three Critical Principles of APX

Discover it?

Explore it?

Access it?

Build on it?

Verify it?

Run on it?

Say goodbye?

Checklist

Publish it?

Describe it?

Expose it?

Implement it?

Sandbox it?

Operate it?

Version/deprecate?

How Will You…. How Will They….

Discover it?

Explore it?

Access it?

Build on it?

Verify it?

Run on it?

Say goodbye?

Solution

Publish it?

Describe it?

Expose it?

Implement it?

Sandbox it?

Operate it?

Version/deprecate?

How Will You…. How Will They….

API Portal RAML tooling

API Manager

APIkit Mule/

ClToudHub

API Manager API Portal

What Kinds Of API?

What Kinds of API?

SOAP and WSDL over HTTP

REST: HTTP taken seriously •  e.g. GET /users ß a page/data representing users

Mix & Match:

•  Google protocol buffers over HTTP •  <something> over websockets

API facades:

•  the RESTmullet (REST in front, SOAP in back)

•  mobile REST/GPB/MQTT on top of SOA

What Kinds of API?

SOAP and WSDL over HTTP

REST: HTTP taken seriously •  e.g. GET /users ß a page/data representing users

Mix & Match:

•  Google protocol buffers over HTTP •  <something> over websockets

API facades:

•  the RESTmullet (REST in front, SOAP in back)

•  mobile REST/GPB/MQTT on top of SOA

My Focus Today

Why REST? It’s simple!

•  /users •  /users?zip=94301&subscribed=true •  /users/me •  /users/5638

•  /users/5638/books •  /users/5638/books/20467

•  /books •  /books/20467

Nouns: Resources Carefully consider your domain objects Query params are refinements on resources

Verbs: Methods

GET retrieve (idempotent!)

POST create in container

PUT update – replace (usually)

PATCH update – partial

DELETE remove

HEAD GET w/o body (headers)

OPTIONS metadata, e.g. methods

Status codes •  Standardized

•  Use them!

•  Don't return 200 unless it's really OK

•  No surprises pleas

Headers •  Standardized

•  Use them!

How to describe your specific API?

Your Answer: RAML

Clean, clear, powerful 100% natural & organic

Open, vendor-neutral Practical

Pattern-based design is built in

RESTful API Modeling Language

API Design Considerations

Align to a logical model: users & groups

Align to a logical model: eCommerce

collections and members

Patterns: resource types

"special" id's

one-off resources

read-only resources

Patterns: method traits

Patterns: body schemas

or just use good ol' form data:

XML schema

JSON schema

examples

Patterns: security schemes

username/password; cleartext or use digest

end user allows app to access their data

better to put token in header, not query

the OAuth multi-step dance

Username/password:

• End-user vs server • Who stores credentials? • Beware of reuse; if you do store, one-way hash w/salt • Minimize client & in-transit exposure

Tokenization

• Short-lived and long-lived; refreshing

• App token vs user tokens

OAuth2 if you need 3-way

auth

•  Be aware of its types •  Don't reinvent this

particular wheel

Elements of API security

HTTP security

principles still apply

•  Beware of chatty errors

•  Good URL hygiene

The nature of the API

Coarse-grained or fine – chatty or concise? Usecases! à you often need both

Latency: remember the speed of light

Bandwidth a problem? Compression, tokenization

Partial requests and responses

Reconsider format and protocol

Implementability? Befriend your integration/orchestration layer

Think layers; think cacheing

Good APIs aren't trivial

But with the proper approach, they can be your home-court advantage "First one home wins?" "Deal"

"#$*%!"