Happy Business Starts Here

New Student

New REST API document and sample code

Hello,

 

I have been integrating your new REST API into our solution and using the codelibrary-dot net starter kit that is provide by Zuora. Here are some reference links:

 

https://github.com/zuora
Code library - https://github.com/zuora/codelibrary-dotnet

 

So far I have had great success with the code libraries and the new REST interface. It seems a bit faster than SOAP. However, I think there is a (documentation) problem with some of the required fields when creating an account via CRUD. If you want to create an account, the first thing you do is create a ProxyCreateAccount object. This object requires BALANCE field, as per the documentation here:

 

https://www.zuora.com/developer/api-reference/#operation/Object_POSTAccount

 

The ProxyCreateAccount enforces this requirement and will not allow null values in the constructor:

 

// to ensure "Balance" is required (not null)
if (Balance == null)
{
      throw new InvalidDataException("Balance is a required property for ProxyCreateAccount and cannot be null");
}
else
{
      this.Balance = Balance;
}

 

Note: The functionality in the constructor above matches the documentation - which says the field is required. However, if you actually try to submit a new account request when the Balance field specified, it will error. This makes sense, it is an autogenerated field. It is similar to other required balance fields (invoice balance, credit balance). They are marked as required, but they are required to be absent for a new account. 

 

I got past this easily - simply comment out the code in the constructor that would require it. When I did this, the accounts created without issue.

 

Note: I recognize that the code codelibrary is "as is" - so far it has been great. The intent here is just to improve things.

 

Thanks,

Dirk

4 REPLIES 4
Community Manager

Re: New REST API document and sample code

Thanks for your input, @dfrulla!

 

I'll pass this along to our docs team to have a look at it and check-in here with you about it.

 

Lana


Lana Lee | Senior Community Manager and Strategist
"A little consideration, a little thought for others, makes all the difference." —A. A. Milne
Community Manager

Re: New REST API document and sample code

Hi @dfrulla,

 

I reached out to the documentation team and they’re working on it. Thanks for the heads up and please let us know if you find anything else that needs our attention.

 

Thanks,

 

Lana


Lana Lee | Senior Community Manager and Strategist
"A little consideration, a little thought for others, makes all the difference." —A. A. Milne
Highlighted
Scholar

Re: New REST API document and sample code

@dfrulla we had a load of issues using the generated code from the swagger. 

 

One thing that you'll have a hard time getting anyone to admit is that currently auto generated code from the YAML files is unsupported and wrong in so many places. In our implementation we have an open risk item that says that we should not be using the yaml files. You should raise this with your implementation PM as it is well known just not talked about. 

 

 

Also note, that one of our big stumbling blocks was dates and times. Zuora has wrapped old SOAP services that produce one time format and the new Rest services produce a standard time format. The result is that different endpoints will produce different time outputs (there have been comments in other places about timezones also being wacky). 

 

Next, there is no change management in place for the swagger file. In March Zuora completely changed the backend object model naming without any form of communication. 

 

It's a little sad that, you weren't told this officially by Zuora or as the first response in this thread. 

 

So to re-state base on our own pain and our outstanding issues - the autogen code is not usable for production and for us it hampered our development process. 

 

If you want proof, you should open and read the YAML file https://www.zuora.com/developer/API-Reference/ -> https://www.zuora.com/wp-content/themes/zuora/css/swagger.yaml?v-4.2.1

 

 termsOfService: |
    
    *************PLEASE READ BEFORE USING THIS SPECIFICATION*********************
    
    This OpenAPI specification of the Zuora REST API is provided “AS IS”, for reference purposes only. 
    Zuora does not guarantee or make any representations regarding the use, results of use, accuracy, security, timeliness, or completeness of any data or information provided in this specification. 
    If you, the customer, use this specification in your implementation, you are responsible for making sure that your implementation is functional and secure. 
    
    Go to [Zuora Community](http://community.zuora.com/) to report issues or discuss this specification with your peers. 
  
    *****************************************************************************

 

New Student

Re: New REST API document and sample code

@evan

 

I did notice it was AS IS. Right now we don't have any of the REST libraries in production code, but we are fussing around with them to see how they work. We have a combination of REST and SOAP calls now (our own custom libraries) - has been that way ever since the beginning. We liked REST, and thought it would be possible for all of our uses, but quickly found out that we needed to fall back on some of the extended SOAP functinality.

 

Notice, though, that the code that was generated MATCHED the documentation. The documenation explicitly said that Balance and InvoiceBalance were requried fields, and the constructor attempted to inforce this. I haven't checked back since my post. It wasn't just a case of the generated libaries being out of date with the YAML - the current documentation was wrong. Maybe they have been fixed. However, they are simply not required. In fact, the exact opposite.

 

I don't doubt there are issues. I am OK with fussing with the library and improving it. Regardless of the code we use, we end up testing everything over and over. Our custom libraries have had their share of bugs too.

 

Are you using the .NET version of the autogenerated code? I haven't seen any issues with dates yet. They seem to serialize into the native DateTime with out any issues. But then again, I haven't gotten TOO far into it...

 

Thanks,

Dirk