Web Services 1.0 versus 2.0
All Web Services that have a class name that ends with 20 are new. This topic gives an overview of the most important changes and should be read in case integrations were built using the Web Services delivered with release 3.2.x or older.
DocumentObj became DocumentObj20
Which version should I use?
The version described in this documentation set should be used when building new integrations.
Authoring Context became an in/out parameter
Authoring Context (also known as authentication context) now contains an expiration time out. The Web Services 2.0 regularly reset the expiration time-out (encoded in the context) and therefore it returns an updated context.
Behavior of Version Numbers
When branching was introduced, the type of a version number became more complex (string instead of integer). Also keywords (new, latest, etc.) were introduced. See also Behavior of Version Number.
IshObjectList as all-round data structure
DocumentObj (1.0) interface returned XML documents that included a metadata section. This approach had the following limitations:
- It is not possible to retrieve the metadata when no blob is available in the repository
- It is not possible to store metadata in a binary object (e.g. illustrations (images))
- Since the metadata was stored in the XML document, the XML document was no longer valid (unless the DTD was adjusted accordingly).
The DocumentObj2.0 class always return an ObjectList XML Structure in which objects from the database are base-64 encoded.
Modes for Product Definition
Some functions in DocumentObj (1.0) had a psMode parameter that was intended for future use. As it was not present in all functions, it was decided to encode this parameter within the Product Definition XML Structure.
The expand master option is replaced by the baseline concept
Since release 3.1, a ‘baseline object’ is used to stored version information on the links between different objects (master documents (maps), modules (topics), illustrations (images), …).
DocumentObj (1.0), the function GetDocObj had a parameter that could be used to expand a master document based on a given metadata filter. As metadata filters can’t express all baseline possibilities, it was decided to remove this parameter. Following algorithm leads to the same functionality:
- for the requested master document (map).
- Create a ‘dummy’ baseline report for the master document (map).
- Complete the dummy baseline report in the necessary mode.
- Use to retrieve the necessary objects and metadata from the repository.
Explicit metadata filters in mass retrieve functions
The mass retrieve functions RetrieveMetadata and RetrieveObjects had three implicit filters on metadata: language, resolution and statusgroup. Only statusgroup is kept within the DocumentObj20 interface, the other two can be expressed as explicit metadata filters. Like this, the parameters are the same as for the Find function.
Throwing/Catching SOAP Exceptions
All web services 2.0 throw exceptions. By definition by reference/out parameters do not contain any value when an exception is thrown. For example: the DocumentObj20.CheckOut function on an object that is already checked out, throws an exception with a message body such as, [-119] The object is checked out by 'Admin'., rather than returning a value for CHECKED-OUT-BY.