Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Building the Next Generation of QuickBooks App Integrations, QuickBooks Connect 2017


Published on

Developer Track presentation from QuickBooks Connect San Jose (Nov 2017). Learn about the latest innovations for QuickBooks app developers.

Published in: Software
  • Be the first to comment

Building the Next Generation of QuickBooks App Integrations, QuickBooks Connect 2017

  1. 1. Peter Vogel, Solutions Architect, Intuit Developer group @IPPAlphaGeek Building the next generation of QuickBooks app integrations 11/17/17 #QBConnect | WiFi: QBConnect Password not required
  2. 2. 2 #QBConnect@IntuitDev 3rd-party developer using IDN & QuickBooks SDK since 2001 Joined Intuit Developer team in 2002 Variety of roles at Intuit: Developer Support Engineer SDK Product Manager Developer Support Manager Group Product Manager for Dev Products Founded Intuit Partner Platform About today’s speaker Peter Vogel Solutions Architect @IPPAlphaGeek
  3. 3. 3 #QBConnect@IntuitDev What is V4 Core V4 Principles Central Concepts of V4 Brief Look: The Domain Models of V4 DEMO: V4 APIs via REST and QBO’s own interactions Agenda
  4. 4. 4 #QBConnect@IntuitDev Not just a new API version: V4 is a program to bootstrap the Intuit QuickBooks Platform • Until V4, we’ve been a product with an API (and you have felt the pain daily) • Until V4, QuickBooks Online used over 600 (steadily growing) single-purpose API endpoints for itself (and we felt that pain daily) • Neither V3 not QBO’s own organically developed API were maintainable “as is” What is V4?
  5. 5. 5 #QBConnect@IntuitDev V4 is transformative • For the first time in Intuit’s history, we’ll be “eating the same dog food” that we give to you, our 3rd-party developers • QuickBooks Online use cases drive a different way of thinking about the API – Concepts don’t change – How we expose those concepts changes – It is possible to map V3 APIs to V4 equivalents and vice versa • Our recently announced Turbo product is also V4-based. V4 goes beyond QuickBooks, to all of Intuit. What is V4?
  6. 6. 6 #QBConnect@IntuitDev To • One API • API as a Product & Orchestration • API-based developer experience • Developer experience w/ TTFHW < 5 min • Isolated and encapsulated services • Configuration-based variability From • Internal vs External API • Offering/project-specific API • Service-based developer experience • Effort/time-consuming app development • Monolithic applications • Customization/connect-the-dots for variant features V4 Platform Vision A coherent API realized by isolated and well-encapsulated services to enable developers to build applications quickly and cost-effectively
  7. 7. 7 #QBConnect@IntuitDev API is a product! Developers are our customers • API design is client-centric, not service-centric • Any potential client, not just a single use case • Deep documentation. Docs tell a story Seek better abstraction within the domain language • Common mistake: designing service resources that directly reflect implementation or DB model • Better = Benefit to the user of the API, not necessarily higher order • Example: Transactions and Links vs Deep type hierarchy and “helper objects” like “Undeposited Transaction” Resources/Nouns over Verbs where appropriate • Example: Send invoice as mutation of Invoice, not controller resource • Don’t let RESTafarian idealism trump usability Our internal principles for API design
  8. 8. 8 #QBConnect@IntuitDev V4 logical architecture API GW/ PAS V4 Service (Contact) V4 Service (Ledger Account) V4 Service (Invoice) V4 Service (Transactions) Batch Protocol (AIP) Mobile Client Web Client 3rd-party Apps Graph, Batch, REST APIs API GW: Routing, Throttling PAS : Graph, Batch, REST APIs < Batch Protocol V4 SDK V4 SDK V4 SDK V4 SDK V4 Graph/API Definition V4 Event Bus Capability APIs Experience APIs V3/V4 Translation GW
  9. 9. Central Concepts of V4
  10. 10. 10 #QBConnect@IntuitDev Problem: • XML is fragile, fields not in the original schema cannot be added without potentially breaking apps. • XML is bulky: every field name is repeated twice leading to shortening of field names in the API • XML lacks expressiveness: how can you tell null from not present from blank? • Still want a way to describe the scheme of the data to enable code generation. Solution: • JSON is relatively compact, well-understood, ”native” to browsers, supported by all major languages for wire- >object and object->wire transformations, easy to read. • New fields are absorbed easily by all major implementations of JSON. • Null is different from ’ ‘ is different from not present. • JSON Schema is an industry standard means of describing the “shape” of JSON data with YAML as an excellent input source to code-generation tools. JSON only
  11. 11. 11 #QBConnect@IntuitDev Problem: As you move from region to region, or even preference to preference, business logic constraints for what fields may or may not be enabled, required, etc., change. In V3 you had to query the Company and Preferences object, read a bunch of documentation, connect the dots, and then make your best guess as to what data was or want not required. Solution: Every object contains a “meta” version of itself with each field containing an object describing the variability characteristics of that field in the real object. For example, required or not, enabled or not, min/max lengths, etc. Variability
  12. 12. 12 #QBConnect@IntuitDev Problem: As you move from region to region, or even preference to preference, the data that QBO populates into various transactions by default is not at all easy to determine and is driven by QuickBooks business logic taking into account both region, user preferences and even certain user selections (i.e. choosing a vendor in a bill form can fill the bill with the contents of the previous bill from that vendor). Users can choose to “memorize” transactions to stamp out a new one periodically Solution: Template objects (default being my personal favorite) that you can query to obtain a pre- populated new transaction ready to be fleshed out and POSTed to create a new transaction! Templates
  13. 13. 13 #QBConnect@IntuitDev Problem: Small business is a very complex set of domains with many references to other types of data. This can lead to excessively chatty clients following lots of references or creating/finding lots of objects and then referencing them. For the UI to perform well, we should be able to get the data we need in a properly structured form with only the data we need and nothing “extra,” even though that data is needed in other use-cases and other forms. Solution: Instead of defining “reference” types that hold a subset of information about an entity referenced by another entity (e.g., the customer associated with an invoice), we simply define the field to be of the appropriate entity type: invoice: customer: $ref:/network/contact … This allows the entire contact to be returned as part of the invoice, not just the id and name. It also allows you to express the intent to create the invoice and the customer in one shot! Graphs, not references
  14. 14. 14 #QBConnect@IntuitDev Problem: The QBO UI involves many complex interactions with thin slice of a very large graph. For a client (including the QBO UI) to perform well, we should be able to get the data we need (but nothing we don’t need) in as few round- trips as possible. Facebook’s GraphQL is ideal for this scenario. At the same time, we want the API to be easily accessible and explorable, and to make the transition from V3 to V4 an easy one. Further, data is frequently “owned” by different masters in the small business space. For example, the existence of a contact belongs to QBO’s Network (contacts) domain, but the fact that the contact is an employee and all the data related to that contact’s employment belongs to the Payroll domain. Details about that contact as a customer belong to QBO’s accounting domain. Solution: A combined service gateway and service orchestration layer that provides multiple projections of the underlying domain services: REST, Batch, and GraphQL. Routing requests and portions of requests to the appropriate providers in parallel and assembling the response appropriately. Multiple projections
  15. 15. Brief Look: The Domain Models of V4
  16. 16. Demo: V4 APIs via REST and QBO’s own interactions
  17. 17. The QuickBooks Connect 2017 Conference App The QuickBooks Community Sign in with your QuickBooks login Access the presentations & continue the conversation
  18. 18. Questions?
  19. 19. APPENDIX
  20. 20. 21 #QBConnect@IntuitDev Entity Browser Operations Versioning Relationships Scalars Relationships
  21. 21. 22 #QBConnect@IntuitDev GraphQL Type system Samples Types
  22. 22. 23 #QBConnect@IntuitDev Swagger
  23. 23. Query
  24. 24. 25 #QBConnect@IntuitDev •Prepared Query •Simple Query •Graph Query •By Id Query type
  25. 25. 26 #QBConnect@IntuitDev • Type : entity type being retrieved • Name: Field names expected • Order by • Where : • Simple expression (SE) • LHS : property name • Op: < > != in • Args: array of arguments • compound expression (CE) • Op: (&& ||) • Args: (list of SE or CE) Query types: Prepared Query
  26. 26. 27 #QBConnect@IntuitDev Supports 3 projections • Default projection • SELECT FROM /transaction/invoice • Returns all scalars & compositions • Full projection • SELECT * From /transaction/invoice • Returns what default returns + id for all references. • Custom Projection • SELECT a, b, c, link.* from /transactions/invoice • Returns exactly what was requested • Preferred projection Query types: Simple Query
  27. 27. 28 #QBConnect@IntuitDev { "company": { "ledgerAccounts": { "edges": [ { "node": { balance ”invoices": { "edges": [ { "node": { txnDate amount ”contacts": { displayName } } } ] } } } ] } } } Query types: GraphQL
  28. 28. 29 #QBConnect@IntuitDev • id: Global ID of the entity [ { “id” : "djQuMToxOmRlNWQ3ZmNjMzE:1”}] Query by Id