8. •
tells consumer devs what they'll get
The API Contract Is Critical
•
tells implementer devs what to deliver
•
ensures they'll meet in the end
•
enables parallel development
9. My Experience: Barnes & Noble /
Don't expose dirty laundry
users
products
orders
invoices
the layer cake
of APIs
11. Packaged apps Custom apps Databases
The Traditional Enterprise
The traditional enterprise
sits comfortably behind the firewall
12. Welcome to the New Enterprise
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
13. Connect backend
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
14. Backend to SaaS
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
15. Everything needs to connect
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
16. The Anypoint Platform:
integration on-premises and cloud
SaaS
Packaged apps Custom apps Big Databases / Big Files
SocialCloud platforms
Customers / Partners
/ Suppliers
Mobility and Devices
Anypoint Platform
Business
Insight
Enterprise
Mgmt
Mule Studio
Anypoint
DataMapper
DataSense
Anypoint Connectors
17. The Anypoint Platform:
integration on-premises and cloud
SaaS
Packaged apps Custom apps Big Databases / Big Files
SocialCloud platforms
Customers / Partners
/ Suppliers
Mobility and Devices
Anypoint Platform
Business
Insight
Enterprise
Mgmt
Mule Studio
Anypoint
DataMapper
DataSense
Anypoint Connectors
100,000s
100s
1,000s
1,000,000s
1,000,000,000s
18. The Anypoint Platform for APIs
SaaS
Packaged apps Custom apps Big Databases / Big Files
SocialCloud platforms
Customers / Partners
/ Suppliers
Mobility and Devices
Anypoint Platform
Business
Insight
Enterprise
Mgmt
Studio
APIkit
Anypoint
DataMapper
DataSense
API Gateway
API Manager
Design/Dev Portal
Anypoint Connectors
22. ü
where consumers touch you
ü
your front door, your lobby, your façade
ü
how you want to be seen; your brand
ü
versioned more carefully than code
ü
better interfaces better code
ü
an organizing principle; alignment forcing function
ü
the ultimate testing surface
Focus on the Interface: The Contract
23. 1. Describe APIs simply and clearly
2. Design APIs easily and soundly
3. Engage users in compelling ways
What kind of interface do we want?
NOT documentation
NOT annotations in implementation
24. •
nouns: resources, described by URI paths
•
verbs: HTTP methods
•
metadata: HTTP headers
•
responses: HTTP status codes
•
representations: appropriate media types in the body
•
use hypermedia – not necessarily, not yet
Practically-RESTful APIs
a few words
about REST…
33. •
well-known superset of JSON
•
optimized for human readability
•
great for hierarchies
•
cruft-free
•
broad tooling base
•
extensible-ish
•
broad tooling base
No Need to Start From Scratch!
YAML
34. Introducing: RAML
A new open spec
for RESTful APIs
that's as clean
and as structured
as REST itself
RESTful API Modeling Language
the RAML Workgroup:
raml.org
35. /users:
get:
description: Get a collection of users
post:
description: Create a new user in the collection
/users/{userId}:
get:
description: Get a single user
put:
description: Update a single user
delete:
description: Delete a single user
RAML: How Clean? How Structured?
Take what you would have typed yourself…
39. Covers Full HTTP
optional version in baseUri
template URIs
query parameters
headers (on request and
response)
response per status code
example (and schema) per media
type