Swagger Documentation Inconsistencies

[Jon_Smith]

So I want to point out and suggest some tweaks to the Swagger documentation to make it more sensical aswell as address what I think is an inconsistency.

Lets looks at a simple API call to get a Queue Item

It wants a Key, which should be a long, and requires an OrganisationID (this and many other requests return an error if you do not provide an organisation ID).

Lets now look at a QueueItemDto where you would get information such as the ‘Key’ and ‘OrganisationID’
Here is the Key, but its a GUID, not a long, so its cannot be used to generate a valid API request…

If we go further down we see this.

The OrganisationID is considered deprecated (and has had that note for years) yet is still required for the API call. Very odd.
We also have an ID field with a long data type and indeed this is the value the documentation wants when it asks for a ‘Key’ above.

Surely that swagger stuff is easy to adjust to say it expects an ‘Id’ so it matches the item and to remove that deprecated tag until its actually removed from the requirements of API calls or is properly converted to be ‘FolderID’.

This is not the only place it occurs, Jobs also have the confusing Key =/= Key and expects the ID however that doesn’t say that Org ID is deprecated.