Swagger Documentation Inconsistencies

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.
image

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.

hei @Jon_Smith

All items raised are valid and initiatives we are taking into consideration for our V2/NextGen API offering, in the current form multiple would be changes breaking existing integrations and cause all consumers to undergo undesired refactoring and rebuilds.
Some details for you on the points raised:

  1. The Key field in the request always refers to the Id field from the DTO, changing any won’t be backwards compatible any longer. Furthermore every DTO has a ID and Key Field one numeric and one is a GUID, the advantage of the guid one is that in multi geo setups it is still unique.

  2. Organization_Id: it’s our folder ID and can be queried via the Folders API, it’s a security strengthening measure to always require it for fast authorization checks on requests, on the reply since a queue can be linked and live in multiple folders it’s not a single deterministic field, we still set one for backwards compatibility to not force the use of odata/QueueDefinitions/UiPath.Server.Configuration.OData.GetFoldersForQueue(id={id}) for anyone wanting to determine all.

Hope this clears things up for you and also outlines why for the time being this cleanup is being avoided for backwards compatibility concerns.
Kind Regards, Alex.

I dont fully understand the limitation on this one. In my screenshot no-where does the API call to get the key item use the word ‘Key’, its a placeholder just for the swagger documentation hence me thinking that simply changing it to ID would have minimal impact, perhaps I am missing something though?

Apart from that, sounds good, interesting to hear you are overhauling and I fully agree about providing the folder ID, I was just looking for some consistency (especially if the documentation says its optional when its not :p)