Ross Mason @rossmason

Strategies for

APIs in the

Enterprise

About me

• Created the Mule project• Founded MuleSoft• API eye for the SOAP guy• Thingologist (thingology.org)

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

Why would an enterprise company buy ProgrammableWeb.com?

+ = ?

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

Web APIs are the

Playbook for the

enterprise

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

…or 13,000 ideas

to steal adapt

@rossmason

All contents Copyright © 2013, MuleSoft Inc.#MuleSoftWebinar

RESTful APIs

@rossmason

Open APIs are the tip of the iceberg

13,000

@rossmason

Open APIs are the tip of the iceberg

13,000

1,000,000sof APIsin the

enterprise

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

Enterprise APIs = API delivery at scale

- 3Cs: Clean, Clear, Consistent- Across teams, across orgs- Rapid creation, iteration, lifecycle

management

@rossmason

SOA

API

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

Enterprise SOA

- 3Cs: Clean, Clear, Consistent- Across teams, across orgs- Rapid creation, iteration, lifecycle

management

@rossmason

APIs in the Enterprise

Your APIs

Developer

Customers

Partners

AffiliatesMobile

Internal projects

Your Assets

@rossmason

What we see in the Enterprise

Your APIs

Developer

Customers

Partners

AffiliatesMobile

Internal projects

Your Assets

@rossmason

API types and business opportunities

Source: Forrester, Establish your API design, June 2013

@rossmason

APX: Between Form and Function

APX

Application Programming eXperience

@rossmason

• Design for them• Iterate quickly• Model cleanly and consistently • Engage

Delight your API consumers

@rossmason

• Orchestrating service provider…

• …or core single-purpose service?

• Back end…

• …or front end?

• Straight-through proxy…

• …or new façade?

What is your value add?consumer devs

@rossmason

Think APX!

Don't expose dirty laundry

users

products

ordersinvoices

Craft it for your users: what will they love?

• This is a long-lived interface, • ladies and gentlemen

@rossmason

my focus today• 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

Forms of APIs

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

The 3Cs in Action(Clean, Clear, Consistent)

@rossmason

• Nouns: resources• Carefully consider your domain objects• Query params are refinements on resources• /users• /users?zip=94301&subscribed=true• /users/me• /users/5638• /users/5638/books• /users/5638/books/20467• /books• /books/20467

Practical REST, be Clear

@rossmason

• Verbs: methods

Practical REST, be Clear and Consistent

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 200unless it's really OK

• No surprises please

Headers• Standardized• Use them!

@rossmason

•We like RAML: RESTful API Modeling Language

• Clean, clear, powerful• 100% natural & organic• Open, vendor-neutral• Practical• Pattern-based design

is built in

How to describe your specific API?

@rossmason

Clean, align to a logical model: users & groups

@rossmason

Clean, align to a logical model: eCommerce

@rossmason

collections and members

Consistent patterns: resource types

"special" id's

one-off resources

read-only resources

@rossmason

Consistent patterns: method traits

@rossmason

Be Clear: body schemas

or just use good ol' form data:

XML schema

JSON schema

examples@rossmason

Be Clear: security schemesusername/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

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

Enterprise APIs

- 3Cs: Clean, Clear, Consistent (APX)- Across teams, across orgs (RAML.org)- Rapid creation, iteration, lifecycle

management (APIhub.com)

@rossmason

Good APIs aren't trivial

But with the proper approach…

…they can be your home-court advantage"First one home wins?"

"Deal"

"#$*%!"

@rossmason

All contents Copyright © 2013, MuleSoft Inc.

Thank you

Twitter: @rossmasonCompany: http://mulesoft.com