Designing a Great API Consumer Experience

1,356 views
1,165 views

Published on

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

Published in: Software, Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,356
On SlideShare
0
From Embeds
0
Number of Embeds
46
Actions
Shares
0
Downloads
56
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Designing a Great API Consumer Experience

  1. 1. Lessons From The Battlefield
  2. 2. 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  
  3. 3. Let’s Talk APX Application Programming eXperience
  4. 4. 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?
  5. 5. 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
  6. 6. Think APX 3 Critical Principles To Remember
  7. 7. This is a long-lived interface Expose the interface you want your clients to develop a dependency on. 1 Three Critical Principles of APX
  8. 8. 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
  9. 9. 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
  10. 10. 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….
  11. 11. 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
  12. 12. What Kinds Of API?
  13. 13. 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
  14. 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 My Focus Today
  15. 15. Why REST? It’s simple!
  16. 16. •  /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
  17. 17. 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!
  18. 18. How to describe your specific API? Your Answer: RAML
  19. 19. Clean, clear, powerful 100% natural & organic Open, vendor-neutral Practical Pattern-based design is built in RESTful API Modeling Language
  20. 20. API Design Considerations
  21. 21. Align to a logical model: users & groups
  22. 22. Align to a logical model: eCommerce
  23. 23. collections and members Patterns: resource types "special" id's one-off resources read-only resources
  24. 24. Patterns: method traits
  25. 25. Patterns: body schemas or just use good ol' form data: XML schema JSON schema examples
  26. 26. 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
  27. 27. 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
  28. 28. 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
  29. 29. Good APIs aren't trivial But with the proper approach, they can be your home-court advantage "First one home wins?" "Deal" "#$*%!"

×