Presenter: Uri Sarid, CTO, MuleSoft Much like a great UI is designed for optimal user experience, a great API is designed for optimal consumer experience. But what defines great consumer experience? How can developers design an API that consistently meets consumer needs? In this session, we will demonstrate best practices for developing great APIs through collaboration. You will learn: Elements that define a great API consumer experience How to consistently drive API design in every API developed Best practices for API strategy API design pitfalls to avoid Manage Your APIs with Anypoint Platform: https://www.mulesoft.com/platform/api Watch Full Webinar: https://www.mulesoft.com/webinars/api/secrets-great-api

2. Lessons From The Battlefield

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

4. Let’s Talk
APX
Application Programming eXperience

5. 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?

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

7. Think APX
3 Critical Principles To Remember

8. This is a long-lived interface
Expose the interface you want
your clients to develop a
dependency on.
1
Three Critical Principles
of APX

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

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

11. 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….

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

13. What Kinds
Of API?

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

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

16. Why REST?
It’s simple!

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

18. 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!

19. How to describe your
specific API?
Your Answer:
RAML

20. Clean, clear, powerful
100% natural & organic
Open, vendor-neutral
Practical
Pattern-based design is
built in
RESTful API Modeling Language

21. API Design
Considerations

22. Align to a logical model:
users & groups

23. Align to a logical model:
eCommerce

24. collections
and members
Patterns: resource types
"special" id's
one-off resources
read-only resources

25. Patterns: method traits

26. Patterns: body schemas
or just use good ol'
form data:
XML schema
JSON schema
examples

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

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

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

30. Good APIs aren't trivial
But with the proper
approach, they can be
your home-court
advantage
"First one home wins?"
"Deal"
"#$*%!"