Building the Next Generation of QuickBooks App Integrations, QuickBooks Connect 2017
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
#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
#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
#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
#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
#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
#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
#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
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
#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
#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
#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
#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
17. The QuickBooks Connect 2017 Conference App
The QuickBooks Community
qbcommunity.com
Sign in with your QuickBooks login
Access the presentations &
continue the conversation
26. 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
27. 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
Schema.intuit.com
Start with /network/Contact – show composition vs. inheritance, just contact, not Customer, Vendor, employee, etc. Note new stuff there: Client, User, etc.
Continue to /Inventory/Item – again, composition vs. inheritance “traits” concept. No Inventory/Non-Inventory/Service/Bundle item types, but one Item with different traits.
Touch on Payroll CompensationItem, etc.?
Finish with /transactions/Transaction, Line and Links – traits concept goes all the way: ex: invoice and bill both carry a balance and have a person to whom the stuff or payment should be delivered, hence both have balanceTrait and deliveryTrait, etc.
Links: universal way of linking transactions to each other and to specific lines within each other.
Lines: Again, no inheritance, just traits.
NB: USE CLEANED UP VERSION OF SCHEMA
Benefits
Single source of truth
Code-Gen -> Simple POJOs & GraphQL Type system
Express Access
Validations
Benefits
Single source of truth
Code-Gen -> Simple POJOs & GraphQL Type system
Express Access
Validations
As soon as the schema is defined you can immediately query
There is a mock server that provides for loaded schema
This is a great model tool to as you are designing your domain
AST
Providers speak this language
Think of it like a database query
Based format for all communication between providers
Provides abstraction from any language
Un parsed database query
Here for backwards computability reasons (supported by V3 also)
Can be embedded in any of the projections
Provides a short cut
*Returns exactly what you requested
*Type system available to build queries
*Used by facebook & many other companies to build experiences
*