ZUORA APPLICATION RELEASE 212: MAY 2017

[Jiangli]

Greetings,

We are pleased to announce the Zuora May 2017 Release!  Please check out Zuora Release Notes for more details.

The planned deployment schedule is as follows:

• APISandbox Release: 10 pm, 05/10 (Wednesday), PT
• Production Release: 10 pm, 05/17 (Wednesday), PT

No service disruption is expected for this release.

[evan]

Hello Team! Quick one. We noticed a change in your Rest API Docs. It appears that you've changed your entire production endpoint? Where are the release notes? Pretty please with a cherry on top, PLEASE! Post updates to your Rest documents. 

[feisley]

@evan I assume you are referring to the differences between https://api.zuora.com/rest/v1 and https://rest.zuora.com/v1

As you point out these are two different endpoints for production, however, one does not exactly replace the other so to speak.

The https://api.zuora.com/rest/v1 endpoint is the original REST API that has been around for years and contains the traditional REST API.

The https://rest.zuora.com/v1 is the newer REST endpoint that also proxies the legacy SOAP API into it, thus it has the various APIs under the "/action" path. You can think of the new endpoint as a multiplexer for the various APIs as it accepts requests and routes them to the appropriate backend. (i.e. legacy SOAP vs traditional REST, etc). You can read more about this here: https://community.zuora.com/t5/Engineering-Blog/Moving-Fast-from-SOAP-to-REST/ba-p/16160

The point is, any APIs we had developed against https://api.zuora.com/rest/v1 continue to operate as expected, however, newer paths such as "/action/query" are only available under the new https://rest.zuora.com/v1 endpoint since that has to be routed to the SOAP API internally and is a "newer" REST API.

All that being said, the differentation between these two endpoints could do with some documentation to back it up (other than my observations)

DISCLAIMER: This is all from my exploration and testing of the platform and I have no internal knowledge of Zuora's infrastructure. 😉

[Jiangli]

Release 212 was deployed to Production successfully.

[evan]

@feisley thanks for the input. It concerns me that the architectural design now seems split. From your comment it seems that Zuora are moving towards splitting out the old SOAP wrappers. I wish they would give a formal notification though so we could plan appropriately. The trouble is days after the release there still isn't a formal reply. At this stage I'm gravely concerned about our integration project with them because they can't even document changes.

[Shawn]

@evan The REST APIs are new APIs that we released back in Nov, 2016. Below I've linked the annoucement made for this change and the links to the documentation for the APIs. As Feisley stated, these REST APIs are a wrapped to the existing SOAP APIs and are intended to support the same behavior that exists in SOAP today. The older REST APIs are still currenty supported.

https://community.zuora.com/t5/Zuora-Announcements/Announcing-100-REST-APIs-and-New-Developer-Center...

Thank you,

Shawn

[scott]

Hi Evan,

There is no intention at this stage of deprecating the old endpoints. We recommend using REST and our new REST functionality over using SOAP directly, and that any new integrations use the new endpoints via rest.zuora.com, so that's where our documentation points at the moment. The older documentation is still valid and the older endpoints will continue to work.

In some ways the architectural design has been split, in that we are internally migrating to a microservices architecture. This will provide many benefits internally and externally as we move forward. But we have so far managed to implement this significant change without impact to our customers. The consistency and quality of our service remains our top priority.

We will certainly communicate changes and enhancements in the future - we're proud of what we're building and excited about what we will be able to offer our customers as a result of these efforts.

Thanks,

Scott

[evan]

Thanks @scott, your answer was a constructive answer to my comments. I am trying very hard to keep excited about the releases that you're making and our company is invested in Zuora's improvements; but we really need notes when an update is made.

[evan]

@Shawn In the YAML file before may 5th this year this endpoint was referenced in the documents as the correct endpoint: https://api.zuora.com/rest/v1/attachments now it is https://rest.zuora.com/v1/attachments. The update on May 5th changed every other api.zuora.com/rest endpoint to rest.zuora (there were 37 URLS that were updated). 

There are no release notes that document this. You have no change management process for the REST API as far as I can see. If you could please provide release notes on these changes then that would be a really great thing. 

[Shawn]

@evan Thank you for the feedback. I've passed this information on to our documentation teams.

Thank you,

Shawn

[Chunlei]

@evan Thank you for bringing this issue to our attention. 

We do not change the endpoint URLs. In the YAML file, all endpoints URLs are documented using the new URL rest.zuora.com/v1. But unfortunately, the old URL (api.zuora.com/rest/v1) was still referenced in several code samples. We found this issue and updated them to use the new URL (rest.zuora.com/v1) in these code samples in YAML file Version 2017-05-10. 

We understand that it's confusing sometimes without a changelog, we actually maintained an internal changelog for YAML files. But it's not ready to make it customer facing. We are working on it to make it public on Dev Center soon.

Hopefully, this helps to clarify. Thanks for your understanding!

[evan]

Thanks @Chunlei ... when you guys release the notes can you also include cool features like:

/paymentgateways:
get:
description: ‘Retrieves the basic information about all the payment gateways.

This is something that we actually needed, but because you didn't release any notes about it we didn't get to see it. 

Can your team please commit to a public release strategy with a date? 

[evan]

@Chunlei , @Shawn , @scott

Overnight an undocumented change occured. Someone has moved the yaml from https://www.zuora.com/wp-content/themes/zuora/css/swagger.yaml to https://www.zuora.com/wp-content/themes/zuora/yaml/swagger.yaml?v-5.2.1

Can you please document this stuff and send a note around? 

[Chunlei]

@evan When we have the public changelog for API Reference, we will definitely include the cool features as you mentioned. We will try our best to publish the changelog as soon as possible. 

Sorry about the YAML file path change. We changed it to make more sense as we build out more YAML files in our system. Why you reference the file path? If you use this path to download the YAML specification, we suggest you go to https://www.zuora.com/developer/api-reference/ and click the Download button. 

Let me know if you have any further concern. Thanks!

[evan]

@Chunlei we reference the yaml file from code to manage changes as they occur... hense our massive frustration that nothing is documented and that the yaml file isn't representative of what your API's actually produce - it's also why we notice everytime something changes. Our goals is to release our product as up to the minute as possible and that means always validating that we're working in line with the yaml specs. We override where possible. And before you point out the disclaimer, we were in development before that disclaimer was added and we'd already had to work around most of the major differences between your yaml and the actual APIs.