Swagger change request for Sage Accounting API (Page type, and support for NULL values)

[Paul Millard]

Hi there,

I have been working on a solution that utilises the Sage Accounting API.  I installed OpenAPI-Generator-CLI toolkit v6.6.0 to create the required API and Model classes for communicating with our test data, and I have come across some issues that may need to be addressed, or at least documented.

I took the Swagger file which contains ALL of the API classes because the end goal of our solution, is to push Stock, Customer and Supplier contacts, and Sales Invoices into the accounts.  So far, I have got Stock working, and pushing Contacts into the system.  Not without difficulty though.

First of all, literally every endpoint that returns a list of records, requires a new type to be defined in the Swagger file that supports the Page type.  I have gone over this in another thread and a solution was presented to resolve this, but of course, the Swagger file should have been updated by Sage to reflect this need.  Calling any GET endpoint that returns multiple records, causes an exception because of the strong requirement for a Page type to be deserialized.

Secondly, many API endpoint functions return attributes within their respective model classes that have a 'NULL' value assigned.  A good example, is the PostContacts endpoint.  Passing a 'PostContactsContact' type as it's parameter, required the structure to be properly initialised.  But the function would always fail, because the return type 'Contact' contained attributes such as 'credit_limit' and the submember '.TaxTreatment.IsImporter'.  In order to fix this issue, I had to make manual changes to the model classes, and define the types for these attributes, to support the 'NULL' type.  Typically, in CSharp, the property 'CreditLimit' has to be redefined as:

public double? CreditLimit { get; set; }

I do appreciate that OpenAPI v3.0, supported the "nullable" attribute for data members, but was deprecated in v3.1.  But a replacement method was used to define whether a member supported a null, by using the 'oneOf' attribute:

"type": {
  "oneOf": [
	- "double"
	- "null"
  ]
}

Apart from this issue, the other problem is when actually generating the model classes using the OpenAPI-Generator-cli tool, but this is not an issue for this forum.  Either way, it must be clear on the API documentation that return types which support NULL, must be shown to do so!  Much time was wasted trying to figure not only why I was getting errors when calling the API, but to figure out which model structures, were causing the errors and to modify the classes respectively based on the response text from the API.

I hope this information proves useful, and to help Sage improve their API documentation and Swagger file respectively.

Regards,

Paul.

[Steel, Mark]

Hi Paul,

Thank you for your insightful feedback. There's now an internal ticket(SBS-68065) on the backlog to make the improvements you've brought to our attention. 

We'll update this thread before we push those changes live. 

Thanks

Mark