Design & Deploy a data-driven Web API in 2 hours

2,378 views

Published on

Learn how to use the ROA/D process along with UX and DDD to design a proper web API, then learn how APISpark platform (PaaS) compares to a DIY approaches.

Published in: Technology
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,378
On SlideShare
0
From Embeds
0
Number of Embeds
68
Actions
Shares
0
Downloads
35
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

Design & Deploy a data-driven Web API in 2 hours

  1. 1. DESIGN & DEPLOY A DATA-DRIVEN API IN 2 HOURS All-in-one platform for Web APIs http://apispark.com Restlet undersigned this GigaOM research report, written by Kin Lane October 23, 2013
  2. 2. PRESENTER ENTREPRENEUR AND WEB API EXPERT Jérôme LOUVEL       CEO of Restlet 12 years of experience in software (EU and US) Restlet Framework creator (2005) JAX-RS 1.0 expert (JSR-311) Contributor to “RESTful Web Services” (O’Reilly) Co-author of “Restlet in Action” (Manning) Contact  jlouvel@restlet.com  Twitter : @jlouvel and Google+  Blog : blog.restlet.com
  3. 3. AGENDA  Part 1 – API design – Info: The ROA/D to API design – Lab: Specify your Pizza API  Pause  Part 2 – API deployment – Info: APISpark as an IDE and runtime – Lab: Deploy your Pizza API
  4. 4. Info : The ROA/D to API design PART 1 - API DESIGN (15’)
  5. 5. HOW TO DESIGN MY API?  Let’s pick up a web API framework and prototype!  I’ll read and digest REST dissertation first  APIs are lighter Web Services, nothing new  Let’s look at popular APIs and follow best practices  My API should have nice URIs and CRUD methods  Which kind of design process should I follow?  Many ways to tackle this…
  6. 6. METHODOLOGY  Resource-Oriented Analysis & Design – Based on our consulting experience at Restlet – Variant of OOA/D described in « Restlet in Action » book – Usable on Agile projects and with Lean approaches Learn about the ROA/D methodology !
  7. 7. ITERATION STEPS Requirements gathering Implementation testing Design implementation Requirements analysis Solution design
  8. 8. PROJECT PHASES  Each phase contains – Several iterations – More requirements & analysis in early phases – More implementation & testing in later phases Inception Elaboration Construction Transition
  9. 9. & UX Design for API Developers Requirements gathering • UX != UI  UXD != API • Similar process: – User research  Persona  Use case  Feature(s) • Enrich ROA/D during – Requirements – Analysis Requirements analysis • Based on Nazmul and Izabel Idris workshop for Google I/O 13 – http://bit.ly/uxcommunity – Adapted to web APIs by APISpark with help of SFEIR
  10. 10. DESCRIBE API PERSONAS • Bart is a Mobile app developer – – – – Unreliable networks Pre-fetch and cache data Small data packets best Android first, then iPhone • Homer is a HTML 5 developer – – – – Good connectivity Bigger data for larger screens Same-Origin Policy Works with AngularJS Advises • Contextual and specific to your API • Don’t denature a persona • Don’t support too many personas • Think about game consoles, connected TV / cars, glue scripts
  11. 11. DESCRIBE API FEATURES • Use cases for Bart – Build an iPad app version – Build an Android app version – Build an iPhone app version • Features – – – – Provide an iOS client SDK Provide an Android client SDK Supported GZip HTTP Monitor API traffic per mobile device type Advises • Identify use cases per persona • Derive features from concrete use cases • Be careful about feature creep!
  12. 12. BALANCE API FEATURES SIMPLICITY VS CAPABILITY Complexity Powerful but unusable Adding features Your web API sweet spot Bad UX design Good UX design Simplistic and frustrating Capability Adding features
  13. 13. & Domain-Driven Design for API Developers Requirements analysis • When your domain isn’t trivial • Key building blocks – Entity – Service – Repository • Enrich ROA/D during Solution design – Analysis – Design • Based on Eric Evans book
  14. 14. IDENTIFY DOMAIN ENTITIES Advises Customer • Defined by thread of continuity Invoice Order • Has own identity ? • Not defined by its properties ( value objects)
  15. 15. DESCRIBE DOMAIN ENTITIES Advises Customer id : String name : String created : Date modified : Date • Describe properties 1 * Invoice id : String amount : Integer iterms : List<InvoiceItem> modified : Date * Order id : String amount : Integer iterms : List<OrderItem> modified : Date • Describe relationships • Use class diagrams
  16. 16. Next design steps are more API specific Requirements analysis • Define your logical architecture – Learn about Netflix API strategy • Derive your domain entities into – API resources – Domain objects – Data tables Solution design • Design your API resources – URI templates – Representations structure – Supported HTTP methods
  17. 17. LOGICAL ARCHITECTURE UI API resources Domain objects Data tables _ + Reusable
  18. 18. DERIVING THE DOMAIN MODEL Domain entities ROA/D API resources ROM OOA/D Domain objects IDEF1 ORM Data tables
  19. 19. IDENTIFY YOUR APIS Advises Browser Connected mobile devices Smart environnement • Driven by personas Pages + API • Each persona might need a specific API Domain Model Partner Internal IS • All APIs should share the same domain model
  20. 20. DESCRIBE API RESOURCES Advises Root http://localhost:8111/ GET() : xml | json | html • Driven by use cases 1 Accounts 1 accounts/ • Derived from Domain Entities GET() : xml | json | html POST(xml | json | form) : redirect 1 Account * {accountId}/ GET() : xml | json | html PUT(xml | json | form) : xml | json | html DELETE() : redirect • Several APIs for on domain model
  21. 21. Lab : Specify your Pizza API PART 1 - API DESIGN (50’)
  22. 22. & Requirements gathering Requirements analysis
  23. 23. DESCRIBE PIZZA API PERSONAS Instructions • Contextual and specific to your API • Don’t denature a persona • Describe a total of 2 personas • Time limit: 10’
  24. 24. DESCRIBE PIZZA API USE CASES Instructions • Put your persona in context with use cases and derive features • Describe a total of 4 use cases (2 per persona) • Identify key features • Time limit: 10’
  25. 25. & Requirements analysis Solution design
  26. 26. DESCRIBE DOMAIN ENTITIES Advises • List 4 entities • Describe their properties • Including relationships • Time limit: 10’
  27. 27. IDENTIFY YOUR APIS Advises • Driven by personas and features • Describe 2 endpoints (1 for each API) • Several APIs should share the same domain model • Time limit: 5’
  28. 28. DESCRIBE API RESOURCES Advises • Driven by use cases • Derived from Domain Entities • Single and collection resources • Time limit: 15’
  29. 29. Solution design Next steps are about API deployment • Implement the Domain Entities – As a persistent store • Implement the Resource Model – As a Web API connected to the Domain Entities Design implementation • Choose between DIY and PaaS approaches
  30. 30. TIME FOR A BREAK ! (10’)
  31. 31. Info : APISpark as an IDE and runtime PART 2 - API DEPLOYMENT (5’)
  32. 32. WEB API PROJECT TYPICAL LIFE CYCLE 1) Do It Yourself (DIY) long, risky, expensive but highly flexible Create Host Manage Use 2) Platform as a Service (PaaS) integrated, fast, cost effective Promote
  33. 33. APISPARK PLATFORM CURRENTLY IN RESTRICTED PUBLIC BETA Send us your feed-back and help us making it the best PaaS for Web APIs !
  34. 34. COMPOSING APISPARK CELLS Java iOS HTTP JS HTTP Custom API Entity Store File Store
  35. 35. STRUCTURE OF WEB APIS HTTP HTTPS API Contract Web API template Complete web API Implementation Runtime
  36. 36. Lab : Deploy your Pizza API PART 2 - API DEPLOYMENT (35’)
  37. 37. SOCIAL LOGIN
  38. 38. YOUR DASHBOARD
  39. 39. ENTITY STORE CREATION
  40. 40. ENTITY PROPERTIES
  41. 41. WEB API CREATION
  42. 42. API GENERATION FROM ENTITY STORE
  43. 43. API DEPLOYMENT
  44. 44. CLIENT SDK GENERATION
  45. 45. Next steps are about closing the API loop Design implementation • Verify that the API works as expected – Manual tests – Automated tests • Functional tests • Performance tests (availability, latency, throughput, etc.) Implementation testing • Even more important in case of composite APIs
  46. 46. API TESTING WITH HTTP CLIENT
  47. 47. BUILT-IN ANALYTICS
  48. 48. CONCLUSION  Designing a web API requires thinking – The UX of developers using your API matters – Use a minimal but effective process  You can save a lot of time at deployment – Consider PaaS solutions versus DIY approaches – Easier and cheaper to get started and maintain – Think about multiple APIs and versions in 2 years
  49. 49. KEEP IN TOUCH! http://apispark.com http://blog.restlet.com Twitter: @apispark jlouvel@restlet.com Restlet undersigned this GigaOM research report, written by Kin Lane

×