General issues with ADOxxWeb API

Detailed issues for each operation that doesn't work are documented as individual issues of the specific projects:

• ADOxxWeb DAO Service
• ADOxxWeb Read Service
• ADOxxWeb Write Service

Following some general issues about the ADOxxWeb API as a whole:

• For some operations the description could or must be improved, e.g. mandatory parameters, enumerable parameter values, parameter types (integer values are still denoted as string), parameter descriptions etc. One specific example: attributetype of /instance/getAllAttributesOfType requires very specific values that are not documented in the API description, otherwise calling the operation leads to a 500 code (server error). The values that need to be specified are also different in structure, attributetype of /instance/getAllAttributesOfType requires an entirely uppercase string while direction of /instance/getConnectors requires a lower case string or it is ignored without any notification that it is wrong. Another example: The /model/getModelsADL operation has an options parameter but it is not stated anywhere what the possible options are or what they would mean.
• There are also some annoying inconsistencies. Some examples (not exhaustive):
  • Some operations that return an ID provide it in the correct data type (integer) but lists of IDs are returned as an array of strings and when the list is empty then the array is not empty, but contains one entry (an empty string).
  • Some indexes start at 0 (/instance/getInterrefAttributeValue), others at 1 (/instance/getRecordRowAttributeValue).
  • Both the /model/getImage/{modelid} and the /model/getImageMap/{modelid} operations have a scale parameter, however one wants a floating-point value (even though parameter type is specified as string) and the other wants an integer value specifying the % (also parameter type specified as string).
• In some cases the amount of necessary parameters seems excessive. For example for /instance/deleteRecordRow: if I already have to specify the rowid why is the objectid and attributeid still necessary?
• The distinction between when an ID and when a name should be specified could be improved.

Also the "REST" interface is more of "just an HTTP" interface. It ignores parts to make it RESTful like using HTTP methods on resources. Specific example: retrieving an attribute value (/instance/getAttributeValue) and modifying an attribute value (/instance/setAttribute) uses different URLs, instead of having one URL (/instance/{instanceid}/attribute/{attributeid}) to represent attributes in general and is detailed through path (or query parameters if there really is no other way) parameters and the distinction between "get attribute" and "set attribute" is calling either GET or PUT (possibly POST, but PUT would be closer to the actual semantics for setting an attribute value).

There are parts in the API that seem to have started going towards a more resource oriented view, but they are also a bit backwards. For example /model/getModelDocuXml/{modelid}, but that is still putting the operation first instead of using HTTP to handle various details, like using GET /model/{modelid} and specifying the Accept header to be either text/xml to get the XML export of a model, image/png to get the PNG image of a model, or a made up text/adoxx-adl to get the ADL export of a model and /model/{modelid}/docu to get a different type of XML representation of the model (getModelDocuXml).