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:
|
||
|
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.
|
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 a |
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:
|
||
|
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:
|
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
|
| 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. | ||
Leave a Reply