Ad
More Related Content
What's hot (20)
Similar to Chris Mathias Presents Advanced API Design Considerations at LA CTO Forum (20)
Ad
Recently uploaded (20)
Ad
Chris Mathias Presents Advanced API Design Considerations at LA CTO Forum
- 1. A Few Advanced API Considerations API Maturity Components
- 2. Chris Mathias Chief Architect, Raken Founder/CEO, SolipsAR [email protected] 602.677.5956
- 3. Why?
- 4. What We’ll Cover I Made This! Now What? With Maturity Comes Knowledge…and Compromise Why are we still using REST? Intentional Limits - Throttling, Burst, Quotas Contract Ownership, Swagger & Static Dev Versioning and Versioning and Versions Coarse vs.Fine Grained Data Sourcing & Freshness Async, Push/Pull…etc
- 5. Why Are We Still Using REST? • HAL • HATEOAS • JSON:API • GraphQL • JSON Schema The Case for RESTful API’s As someone who came up in the days of the CORBA, then the SOAP protocol, I find all these attempts at formalism an ironic conclusion to the "wow REST is so much easier" saga.
- 6. Growing Up (about design) • Simplicity is an outcome of clear understanding • Build what you need, what adds value to the business • When deciding what to build, ask: • What does success look like? • What is success measured by? • Now, what does your API look like, all grown up? “Everything should be made as simple as possible, but not simpler.” - attributed to Albert Einstein
- 7. Contract Ownership Design by Design Swagger & Static Dev
- 8. This Probably Goes Without Saying • Swagger == Modern REST • Open-API Standard == Swagger 2 • Google/Paypal/Adobe/Ebay/Microsoft/Salesforce/Atlassian/SAP/IBM/Oracle/Mulesoft • Tooling curve up & to the right • Standards without rigidity • Doesn’t automatically engender back-end complexity • RAML (I guess Swagger+YAML wasn’t cutting it…) Lets be realistic - sometimes developers “just start coding” to get it done as fast as possible. Thus do we break the "good" leg of the "good/fast/cheap" triangle.
- 9. Design by Consumer… • Lots of Actors • Front End Dev • Back End Dev • Public Consumer • “The Architect” • The Customer is Always Right
- 10. …Then Iterate 1. Front End Developer Designs 2. Swagger YAML/JSON 3. Generated Server & Client 3.1.The Wall is Getting Built. 4. Front End Implementation 5. Oops! Return to Step 1… 6. Working Static Prototype (business says Hooray!) 7. Backend Work 8. Functioning API. Rinse & Repeat
- 11. Some Tools • http://swagger.io • http://raml.org • https://apiary.io/ • https://aws.amazon.com/api-gateway • https://www.getpostman.com/ • http://robohydra.org/
- 12. Intentional Limitations What should we control?
- 13. What Kind of Limits Do You Need? • Rate Limiting (Throttling) - protect well-understood system thresholds • System-based • Client-based • Bursting - allowed overages of limits for special clients or off-peak usages • Metering/Quotas - artificial limits to align to pay-per-use models
- 14. This Sounds Complicated Should I Build It? • API Platform Vendors May be Worth It • https://apigee.com/ • https://aws.amazon.com/api-gateway • https://www.mulesoft.com/ • https://cloud.oracle.com/api-platform • Many Others: https://www.gartner.com/doc/3488151/ magic-quadrant-life-cycle-api
- 15. Versioning This thing will change…
- 16. Version Mechanisms: Access • How Do We Get To The Right Version? • Is There a Right Way? • URL • Header • Content-Type • These Aren’t Really All That Different
- 17. Version Management: Routing • What is Being Versioned? • Models • Parameters • Mechanisms • Altered or Additive or Destructive? • Version Routing • Code-Based (in-app) • Release-Based (extra-app)
- 18. Version Management: Lifespan • How Many Versions? • I like the answer "current - 1" because that makes the preceding slide (legos) a bit easier. • Finite infrastructure cost if I can guarantee that I only ever host 2 versions. • Inevitably though business will find reasons to host more • Like anything, it comes down to finding a good balance. • Internal is easier than external. • Try really hard to limit your public API change rate. • What if No Version is Specified? • Show the latest. • What if That Screws up Customer X? • Meh. Teach your users to always pass a version.
- 20. Dao or Session Facade? • Turns out this is a pretty hotly contested topic! • Many Backend developers: “expose the database on the web” • Let the front end devs or api consumers figure out the rest. • It's the "teach them to fish" approach. • Fine-grained endpoints for every model entity in your API is good, clean, simple to understand and build. • Can really backfire! How many business rules can be circumvented unintentionally here? Just give them the fish, for goodness sake. • Yes: do fine-grained API's, but only for internal consumption • Build Coarse-Grained API's too. I've also used the term "orchestrated" API's.
- 21. An Example Do you want the front end developer or public api consumer to: 1. Create an Account 2. Create a User, manually associating the account id 3. Create a Profile, manually associating the user id with the profile 4. Create Entitlements for the User 5. Log the User in Or do you want an API called "provisionNewUser" that takes a few pieces of info and properly orchestrates that series of calls? If you are on the consumption side, I can predict which approach you might feel more affinity toward. Model your API's after your primary use cases and reduce the heavy lifting. Expose your fine-grained API's surgically where necessary to accommodate corner cases or internal needs.
- 22. API Style Data Sourcing & Freshness
- 23. Asynchronous API • Do You Need It? • What Is Asynchronous API? • Request/Response (no) • Pub/Sub (yes) • Streaming (yes) • Fire & Forget (yes) • No Reactive Ppl, NOT “Everything” is a Stream!
- 24. Does Asynchronous Mean Realtime? • No. But Sometimes It Means Performance. • Data is always old, it’s just a question of how old. • What is Realtime? • As Fast As Possible • Daily Revenue Report? No! • Dynamic Ad Spend Bidder? Yes!
- 25. Data Access Mechanisms • Depending on API Type/Style/Requirements • General Push vs. Pull • Client-Facing or Business Facing? • CRUD API? • Are You a Data Vendor or Provider? Both? • Depending on Freshness Concerns • Polling • Push/Webhook • Dynamic Subscription
- 26. In Conclusion