Content Compare S1000D API endpoints

REST API

The REST API is available at https://saas.deltaxml.com/api/content-compare/v1/S1000D

Content Compare S1000D is a very simple REST API with two endpoints: /compare and /authorise.

Endpoint	Method	Description	Documentation
`/compare`	POST	comparison of two XML files	POST /compare
`/authorise`	GET	refresh access token	GET /authorise

POST /compare

Comparisons are posted using multipart/form-data to

CODE

https://saas.deltaxml.com/api/content-compare/v1/S1000D/compare

Parameter

Description

inputA

REQUIRED

Input A to the comparison. We only display the changes in content from this version.

See information below on how to send input files.

inputB

REQUIRED

Input B to the comparison. We retain the structure of this input in the result file.

See information below on how to send input files.

outputType

Use s1000d (default) to get changes marked up with S1000D markup, or oxygen-tc to get output using Oxygen processing instructions. Other available track change outputs are - arbortext-tc, xmetal-tc and framemaker-tc.

Authorisation

To make a comparison you will need to set the Authorization header to use your id as a Bearer token, for example:

CODE

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

How to Send Input Files

Files can be sent in two ways: URLs, or as raw XML.

URL inputs
For secure URLs set the Content-Type of the inputA/inputB to text/plain .
Here is an example:

CODE

...
----form-boundary-id
Content-Disposition: form-data; name="inputA"
Content-Type: text/plain

https://www.example.com/s1000d/inputA.xml
----form-boundary-id
...

Raw XML inputs
To send raw XML you can send either a raw XML string, or attach an XML file.

Set the Content-Type of the inputA/inputB part to application/xml or text/xml.
Here is an example:

CODE

...
----form-boundary-id
Content-Disposition: form-data; name="inputA"
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<content xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.s1000d.org/S1000D_5-0/xml_schema_flat/descript.xsd">
   <description>
      <levelledPara>...etc...
----form-boundary-id
...

Responses

200 Successful comparison returns the comparison result.

CODE

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dmodule  [
  
<!ENTITY ICN-C0419-S1000D0379-001-01 SYSTEM "file:///ICN-C0419-S1000D0379-001-01.CGM" NDATA cgm >
<!ENTITY ICN-C0419-S1000D0380-001-01 SYSTEM "file:///ICN-C0419-S1000D0380-001-01.CGM" NDATA cgm >
<!ENTITY ICN-C0419-S1000D0381-001-01 SYSTEM "file:///ICN-C0419-S1000D0381-001-01.CGM" NDATA cgm >
<!NOTATION cgm PUBLIC "-//USA-DOD//NOTATION Computer Graphics Metafile//EN" >
]>
<!--
     dmodule and identAndStatusSection elements removed for brevity - they are metadata and boilerplate handling text
-->
<content xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.s1000d.org/S1000D_5-0/xml_schema_flat/descript.xsd">
    <description>
        <levelledPara>
            <title>Brake system</title>
            <para>The most important part of the bicycle is the brake system. Only a minimum maintenance of the brake system is necessary. But, when a problem does occur, make sure you to do the necessary maintenance as quickly as possible. If you do not do this the bicycle will be dangerous to use.</para>
            <para>There are nine different types of brake systems. The one found on most bicycles is the cantilever brake (refer to 
                <internalRef internalRefId="par-0001" internalRefTargetType="irtt07"> </internalRef>).
            </para>
            <levelledPara id="par-0001">
                <title>Cantilever brake</title>
                <para>The brake system (refer to 
                    <internalRef internalRefId="fig-0001" internalRefTargetType="irtt01"> </internalRef>) has these primary components:
                    <randomList listItemPrefix="pf01">
                        <listItem>
                            <para>the brake lever
                                <changeInline changeType="delete">black first cable</changeInline>
                            </para>
                        </listItem>
                        <listItem>
                            <para>
                                <changeInline changeType="delete">the second cablethe</changeInline>
                                <changeInline changeType="add">the</changeInline> brake arm
                            </para>
                        </listItem>
                        <listItem>
                            <para>the brake clamp (also known as callipers)</para>
                        </listItem>
                        <listItem>
                            <para>the brake pads (refer to 
                                <internalRef internalRefId="par-0002" internalRefTargetType="irtt07"> </internalRef>)
                            </para>
                        </listItem>
                    </randomList>
                </para>
            </levelledPara>
        </levelledPara>
    </description>
</content>

GET /authorise

Get updated token information by using your refresh, id, and expiry information you downloaded earlier by passing them as query parameters to /authorise, for example:

CODE

GET https://saas.deltaxml.com/api/content-compare/v1/S1000D/authorise?refresh=ABCDEF123&expiry=1648141119&id=id

The response will be in the same JSON format you received when you requested your token.

Errors

400 Bad Request. Check the error message for details of what may need to be changed when you re-attempt the comparison. If you continue to receive an error, please contact support using our Customer Support Portal and report the error details.

500 Server Error. If you encounter these, please contact support using our Customer Support Portal and report the error details.

Errors will be reported with a parent element of <error> containing these child elements:

<errorMessage> - description of the error
<errorId> - unique ID to track errors
<errorCode> - the HTTP Response code
<timestamp> - ISO 8601 timestamp

An example of an error:

CODE

<error>
    <errorMessage>Parameter output-type value is invalid. Please choose from oxygen-tc or s1000d(default)</errorMessage>
    <errorId>8d395670-2e56-490d-9c3b-f87ee0154f81</errorId>
    <errorCode>400</errorCode>
    <timestamp>2022-03-24T14:19:29.516+0000</timestamp>
</error>

Restrictions

Only S1000D content can be compared. Files will be rejected by the API if they do not conform and you will receive an error.

If you’re getting an error message blocking your S1000D content from being compared, please contact DeltaXML.

Usage Limit

Trial users get 100 comparisons / month.

Paid subscribers get 1000 comparisons / month. To request more, please contact DeltaXML.

To see your current usage, go to Subscription Manager in MyDelta and find the relevant deal. Under the “Quantity” column will be information on your current usage level.

Input Size Limit

There is an input size limit of 5 Mb for each input file for trial users.

Ready to Subscribe?

If you’re ready to subscribe to Content Compare S1000D, please contact DeltaXML.