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

9.
Central Concepts of V4

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

15.
Brief Look:
The Domain Models of V4

16.
Demo: V4 APIs via REST
and QBO’s own interactions

17.
The QuickBooks Connect 2017 Conference App
The QuickBooks Community
qbcommunity.com
Sign in with your QuickBooks login
Access the presentations &
continue the conversation

18.
Questions?

19.
APPENDIX

20.
21
#QBConnect@IntuitDev
Entity Browser Operations
Versioning
Relationships
Scalars
Relationships

21.
22
#QBConnect@IntuitDev
GraphQL Type system
Samples
Types

22.
23
#QBConnect@IntuitDev
Swagger

23.
Query

24.
25
#QBConnect@IntuitDev
•Prepared Query
•Simple Query
•Graph Query
•By Id
Query type

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.
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.
28
#QBConnect@IntuitDev
{
"company": {
"ledgerAccounts": {
"edges": [
{
"node": {
balance
”invoices": {
"edges": [
{
"node": {
txnDate
amount
”contacts": {
displayName
}
}
}
]
}
}
}
]
}
}
}
Query types: GraphQL

28.
29
#QBConnect@IntuitDev
• id: Global ID of the entity
[ { “id” : "djQuMToxOmRlNWQ3ZmNjMzE:1”}]
Query by Id