Generating API clients from the Accounting API Swagger

[Lightyear Developer]

Hi,

We have generated a Java client from the Account API Swagger using OpenAPI Tools.

The Java client successfully generates and compiles but we are having problems calling endpoints that return lists of objects. For example if we call the GET /ledger_accounts endpoint the Java client blows up because the JSON object returned doesn't match what is defined in the Swagger.

The endpoint is documented here as returning an array like this:

[
    {
        "id": "5135bf0b019049c099cedc1a0771cb3a",
        "displayed_as": "Bank Account (1200)",
        "$path": "/ledger_accounts/5135bf0b019049c099cedc1a0771cb3a"
    },
    {
        "id": "6f9ff4f0662944379d64e9c544eac6ad",
        "displayed_as": "Cash (1210)",
        "$path": "/ledger_accounts/6f9ff4f0662944379d64e9c544eac6ad"
    }
]

This looks to match what is in the Swagger and the Java client generated from it.

What is actually returned is this:

{
    "$total": 124,
    "$page": 1,
    "$next": "/ledger_accounts?page=2&items_per_page=20",
    "$back": null,
    "$itemsPerPage": 20,
    "$items": [
        {
            "id": "5135bf0b019049c099cedc1a0771cb3a",
            "displayed_as": "Bank Account (1200)",
            "$path": "/ledger_accounts/5135bf0b019049c099cedc1a0771cb3a"
        },
        {
            "id": "6f9ff4f0662944379d64e9c544eac6ad",
            "displayed_as": "Cash (1210)",
            "$path": "/ledger_accounts/6f9ff4f0662944379d64e9c544eac6ad"
        }
    ]
}

The documented array is embedded in a 'page' object. The 'page' object isn't described in the documentation for this endpoint or the Swagger file.

I suppose the question I have is, are we maybe not supposed to use the Swagger to generate clients i.e. it is only for documentation purposes?

[Ben Smith]

Hi,

Just to clarify in the client thats created by this tool - are you generating the code that handles the responses too? As in my experience its fairly common to use a tool to quickly create the classes/objects, and define the properties etc. via the swagger definition, but haven't specifically come across anyone else thats had an issue with the swagger definition not including the items and pagination metadata before. 

 

Ben

[Lightyear Developer]

Hi Ben,

The tool generates a complete client that includes the object model, and classes for making request/responses.

The pagination metadata is not in the swagger that we can see.

For example the GET /ledger_accounts request is defined in the swagger as having the following response:

"responses": {
    "200": {
        "description": "Returns all Ledger Accounts",
        "schema": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/LedgerAccount"
            }
        }
    }
}

i.e. it says an array of LedgerAccount objects are returned:

 "LedgerAccount": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The unique identifier for the item"
        },
        "displayed_as": {
          "type": "string",
          "description": "The name of the resource"
        },
        ...the rest of the LedgerAccount properties...
      }

If we tweak the swagger and add a 'page' object based on what we see returned by the actual endpoint and update the /ledger_accounts request to reference that rather than an array of LedgerAccount then it all works as expected. 

As an aside is the paging meta data described anywhere in the documentation - at the minute we are calling the endpoint until the '$next' property in the paging meta data is null which seems to work.

[Ben Smith]

Hi,

That makes sense then, and is something we will have to consider going forward for sure, and thanks for clarifying. 

We have a guide on pagination here which details the parameters provided. I would agree that using $next to reach the last page is the best option, and one I've suggested in the past. 

I'd be keen to see the tweak you have made, and will contact you separately about that.

Ben

[Tony Fletcher]

Hi @Ben Smith, are there any plans to update your Swagger file so it shows the correct responses the API returns (i.e. including the pagination elements)? It is 2 years on from this thread and this is still a problem that has not been resolved.

[Ben Smith]

Hi Tony,

Unfortunately not, due to various re-organisations we have different people working on different products now. Whilst I'm not currently working with Accounting, we have provided details of these requests and recommendations to the engineering teams. At this point I can't give you an ETA on it, but I've made the relevant people aware of your request again. 

 

Ben