API Docs & Tools Blog Help
Here Comes V3 - Intuit Developer Community Blog

November 18, 2013 | admin

Here Comes V3

If you are an Intuit Small Business application developer and wondering what QuickBooks Online V3 API could do for you, read on!

QuickBooks V2 API has been around for the last 3+ years and hundreds of applications already implement it to get the data in and out of QuickBooks. If you are a V2 developer and already have a deployed application, you may wonder the need to migrate to V3. If you are new developer the full functionality of V3 is available to you.

V3 APIs were built from the experience of V2: the V3 development team learned from the usage patterns of APIs in V2, listened to developer feedback who were using V2, and addressed most of the V2 issues in V3. As a developer if you are using V3 services, you can do whatever you were doing in V2 services plus you can do more with better performance and ease of development.

The benefits of V3 over v2 services are highlighted in the comparison chart below.

Topic V2 Services V3 Services
QuickBooks Services Focuses on wire format CDM data and structure of QB data. Focuses on services and data content.

Comments:

  • V3 provides more emphasis on REST services and the data associated with these services.
  • V2 is more a extension of QBXML

Hiding product complexity

(Shard hiding)

Developers need to be aware of shard data hosting model in QBO in order to determine the baseURL to use for API calls.
In V2, the developer needs to do the following to call a V2 REST API:

  1. After OAUTH authentication, the developer needs to find the baseURL (or the shard) in which shard on which the company is hosted. To get the baseURL the developer makes a call to the REST “users” API and parses the response to get the baseURL.
  2. Use the baseURL determined in step 1 for any subsequent requests to the REST API endpoints.

No need to find the baseURL for shard information. Simply submit a request to the V3 REST API endpoint.

V3 hides the complexity of the product by introducing a gateway router component that routes the API to respective shard without developer needing to know details of the hosting model. The gateway router is transparent to the developers using the V3 APIs.

 

Comments: QBO services partitions companies into shards. Each shard holds a large number of companies. In V3, the developer need not have to know about shard topology or corresponding baseURLs. V3 eliminates the extra call to find the baseURL. The gateway router component hides the complexity of hosting and provides simplicity for developers.

Data format support XML, JSON, GZIP

Only XML, and GZIP to some extent, are supported.

XML, JSON, and GZIP for compression are supported for all entities.

JSON, along with GZIP, provides a performance benefit in terms of network load between server and the client.

Comments: Supporting multiple data formats provides benefit for the developer to choose the format that best suites the needs.
Simplified Data Model

V2 replicates the concepts in QB (and UI) as data model.

 

V3 rationalizes QB concept into simpler data models. V3 provides a hierarchical data model for certain sets of entities like money-in entities (Invoice, SalesReceipt, Estimates, CreditMemo) that provide similar functionality but differ slightly in behavior.

Several entities that performs the same functionality are grouped as single entity (CreditCardCredit, CreditCardCharge, Check, Cash)

Comments: V3 provides ease of use for developers working with entities. V2 exposes the UI concept as-is and provides as an extension to QBXML.
Customer & Job data model

The Customer and Job entities are exposed as separate entities. Most developers find this separation awkward to implement: if a developer wants to use both Customer and Job, they need to go to two end points “Customer” and “Job” and then merge and sort responses locally.

The Customer and Job entities are exposed as a single entity. They can be queried together or separate based on developer needs.
Comments: V2 exposes role based entity modeling for the Customer, Vendor, and Employee entities. V3 eliminates such complexity by removing role based entity modeling thereby simplifying the data model.
In V3, the Customer and Job entities can be returned in a single V3 API call. Additionally, if a developer needs them separately, he can request them separately.
Expense data model

To record an expense in V2, developers need to use different entities based on the payment type – CreditCardCharge, CreditCardCredit, Check, and Cash. This leads to more code on the client side to do similar functionality.

Expense based entities are grouped into one V3 Purchase entity with type of payment as CreditCardCharge, CreditCardCredit, Check, and Cash. Developers can now use a single Purchase and, based on payment type, can set the CreditCard, Check, or Cash payment type within the object, thereby simplifying coding.

Comments: With V3, client side Purchase code becomes simple. V3 provides a single code for all types of expenses—CreditCardCharge, CreditCardCredit, Check, and Cash, making the code very small and robust.
BillPayment data model BillPaymentCreditCard and BllPaymentCheck are different entities though they perform the same functionality differing only in the payment method.

BillPayment is a single entity with payment type as CreditCard or Check. This allows code reuse and ease of development.

Comments: The simplified BillPayment model in V3 makes the client code small and robust.
Batch Support

V2 supports only single request of any type.

For example, If you create 10 vendors and 10 invoices, you need to make 20 separate API calls. 20 separate API calls get authenticated by Intuit servers resulting in an additional network traffic because the request is chatty.

V3 supports Batch processing of any types of requests and eliminates chatty nature of V2.

For example, 10 vendors and 10 invoices can be created in one single request resulting in a single response. This is a huge performance benefit for clients.

Comments: Significant performance benefit for batch. Provides a batch item request and response.

Any type of entities can be included in a batch request.

Query Service and Simple Query Language

support

V2 supports query with a proprietary format. The developer submits a query request to each endpoint to perform query operations.

To make a query service, the developer has to look deep in the document to understand the supported operations and elements.

V3 supports a single query service endpoint for all queries. Using a SQL-like query language, it is easy to submit a query and get responses for any entity type with support for filtering, sorting, and pagination.

Comments: V3 provides a significant improvement over V2, with support for SQ-like syntax well known to developers, including filters, sorting, and pagination. For example, submit requests to the query endpoint like this:

  • select * from Customer where GivenName = 'Joe' orderby FullyQualiffiedName
  • Select * from Invoice startPosition 5 maxRows 20 // returns 20 rows from 5th row

Partial response support

Need to return full object, no support for partial response

Supports partial response. If an application is interested in only a subset of information available in a V3 entity data record, the application can get that subset of data. This is achieved through the SQL-like query language

Comments: V2 does not support partial data even if an application is interested in only GivenName and PrimaryPhoneNumber in case of the Customer object. The application needs to work with the full data record of Customer even if they don’t use most elements.
In V3, scenarios like this have been simplified by allowing a query to return only the subset of desired fields. Submit such request with the SQL-like query language:
select GivenName, PrimaryPhoneNumber from Customer
Sparse Update support

No sparse update support. Applications need to work with full object even if application wants to change just one element of the entity.

Sparse update is supported in V3. For example, if a phone number needs to be changed in a Customer object, just send only the phone number as part of request, no need to provide the full object.

Comments: Sparse update provides a significant performance benefit by allowing update requests to include only the data which needs to be updated. This reduces the network traffic by improving client and server performance.

Robust service behavior with duplicate submit detection support

Limited support for duplicate submit detection. It is mostly left to client-side code to determine if the submitted request is a duplicate.

V3 supports duplicate detection using a request id mechanism. Each request can be submitted with a request id tag that uniquely identifies the request. QB servers identify the request; if the request has already been executed the server returns the result as an idempotent operation.

Comments: There is a possibility that when a request is submitted by a client and for various reasons client gets disconnected there is no way of knowing if the server processed the request. Client is forced to submit a new request and it may result in duplicated data. In V3 such duplicates are prevented by “RequestId” feature that allows requested to be tagged with an unique identifier, this allows the server to identify if the request is duplicate and responds as an idempotent operation.
Simplified CDC

In V2 in order to obtain all the changes occurring after a certain time, the developer has to make two separate queries:

  • Query the ChangeData endpoint to get all adds and updates for a specific list of entities.
  • Query the Delete endpoint to get all deleted entities.

The CDC endpoint is simplified in V3. A single request to the CDC endpoint allows retrieving all the changes for any QB data, including the CDC data. All added, updated, and deleted is returned in a single response.

Comments: Simplified CDC processing provides better performance and ease of use by developers.

US New Tax Model support

V2 was developed in the 2010-11 timeframe. QBO support for the new tax model was introduced in the QBO the beginning of 2013.

V2 APIs were not upgraded to take advantage of new tax model but supported the older generic tax model for backward compatibility

V3 supports both the new tax model and provides backward compatibility for the old tax model.

 

Comments: V3 is flexible and supports both tax models with ease of development.

Global Support and Global Tax Model support

No support for Global.

V2 provides no support for the Global Tax model. V2 APIs can not be used outside US.

Supports Global multicurrency.

V3 supports the Global Tax Model for any country notably: US, Canada, UK, Singapore, Australia, and India.

 

Comments: True support for global tax model is a big benefit for developers. In addition, there is just single API for US and Global tax.
Transaction Model

Every transaction is considered a distinct transaction. The developer has to write code for each, with limited reuse.

All transactions are derived from a common base class providing significant leverage of Income (money-in) and expense (money-out) entities.

Comments: Provides big benefit for the developers to reuse code.

Comments

View all
Load more comments