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

  • 1,336 views
Uploaded 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.

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.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
1,336
On Slideshare
0
From Embeds
0
Number of Embeds
3

Actions

Shares
Downloads
14
Comments
0
Likes
2

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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. 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. 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. Info : The ROA/D to API design PART 1 - API DESIGN (15’)
  • 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. 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. ITERATION STEPS Requirements gathering Implementation testing Design implementation Requirements analysis Solution design
  • 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. & 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. 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. 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. 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. & 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. IDENTIFY DOMAIN ENTITIES Advises Customer • Defined by thread of continuity Invoice Order • Has own identity ? • Not defined by its properties ( value objects)
  • 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. 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. LOGICAL ARCHITECTURE UI API resources Domain objects Data tables _ + Reusable
  • 18. DERIVING THE DOMAIN MODEL Domain entities ROA/D API resources ROM OOA/D Domain objects IDEF1 ORM Data tables
  • 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. 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. Lab : Specify your Pizza API PART 1 - API DESIGN (50’)
  • 22. & Requirements gathering Requirements analysis
  • 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. 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. & Requirements analysis Solution design
  • 26. DESCRIBE DOMAIN ENTITIES Advises • List 4 entities • Describe their properties • Including relationships • Time limit: 10’
  • 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. DESCRIBE API RESOURCES Advises • Driven by use cases • Derived from Domain Entities • Single and collection resources • Time limit: 15’
  • 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. TIME FOR A BREAK ! (10’)
  • 31. Info : APISpark as an IDE and runtime PART 2 - API DEPLOYMENT (5’)
  • 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. APISPARK PLATFORM CURRENTLY IN RESTRICTED PUBLIC BETA Send us your feed-back and help us making it the best PaaS for Web APIs !
  • 34. COMPOSING APISPARK CELLS Java iOS HTTP JS HTTP Custom API Entity Store File Store
  • 35. STRUCTURE OF WEB APIS HTTP HTTPS API Contract Web API template Complete web API Implementation Runtime
  • 36. Lab : Deploy your Pizza API PART 2 - API DEPLOYMENT (35’)
  • 37. SOCIAL LOGIN
  • 38. YOUR DASHBOARD
  • 39. ENTITY STORE CREATION
  • 40. ENTITY PROPERTIES
  • 41. WEB API CREATION
  • 42. API GENERATION FROM ENTITY STORE
  • 43. API DEPLOYMENT
  • 44. CLIENT SDK GENERATION
  • 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. API TESTING WITH HTTP CLIENT
  • 47. BUILT-IN ANALYTICS
  • 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. 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