New and improved Java SDK for Xero API
We are very excited about changes in our Java SDK. This is a first step towards improved management our SDKs in 2019 and beyond.
JSON all the way
We announced full support of JSON on our accounting endpoints in 2017, but we did not prioritize adding JSON support to our SDK. It’s not that we didn’t see the inherent advantage of smaller JSON payloads over XML, but we’d designed our SDK to handle the marshalling and unmarshalling of XML for developers. Java developers code with Java objects modeled off XSD schema files and don’t need to touch XML, so there was less urgency to add full JSON support.
That changes with version 2.0 of our Java SDK.
Reasons for this update:
- XML is not supported by BankFeeds, Fixed Assets, Projects, Xero HQ APIs
- It’s easier to support one (XML or JSON) and JSON is clearly the future
- XSD model files are only useful for the Java language
- Modern code generators for client libraries use OpenAPI Spec (Swagger)
We are not removing any existing code that leverages XML and the XSD models, so we don’t foresee any impact on integrations built on earlier versions of the Java SDK. If you do upgrade to 2.0 and run into problems, please file an issue on Github so we can investigate. You should consider the XSD models and XeroClient deprecated going forward and no new functionality will be added around them.
OpenAPI Spec 3.0
The Xero’s Developer platform team have been busy updating our API and adding endpoints (History and Notes, Batch Payments and Payment Services). We had a choice between the past and the future. Instead of investing time updating the XSD files, we chose to update our Swagger 2.0 file to OpenAPI Spec 3.0 and added new endpoints. These spec files are the foundation for future updates to our models and client classes in the SDK.
We are very excited about the possibilities around Xero’s OpenAPI spec 3.0 going forward.
Differences between SDK version 1.0 to 2.0
It’s worth mentioning the changes for those wanting to use 2.0 features.
Version 2.0 of the Java SDK implements requests and responses using JSON only. This means, the XeroClient class that holds methods for interacting with each endpoint in XML will be deprecated in favor of clients for each major API group at Xero. See below for a comparison.
Initializing Client
1.0 Client (deprecated)
2.0 Client
Making API calls will change
1.0 Example
2.0 Example GET
Models are moving
1.0 models where imported from com.xero.model.*
2.0 models are separated into major API groups under com.xero.models i.e. com.xero.models.accounting.*
Maven Central
Version 1.0 of our SDK utilized a branch off our Github repository to serve up maven dependencies. It was simple and worked well for our initial release, but we received feedback about other dependency management tools beyond maven like gradle and sbt. Developers were struggling to use these tools with our non-standard way of hosting our dependencies.
I’m happy to announce our Java SDK is now available on maven central starting with version 2.1.0. Head over to maven central to find dependency configuration details for your next Java project.
If you are just starting out, check out our new “hello organisation” video.
