Migration Guide

This page outlines the changes that have been made to the API since version 1.0 was launched in March 2008. We understand that changes to an API directly impact your code and have made every attempt to keep the changes we require you to make at a minimum. This document outlines the changes that you will need to make to your code when you move to the new version of the API. Note that the functionality that was provided in the 1.0 release of the API is referenced throughout the new API documentation as the Signature Service.

Changes to the Call URL

The call to the API system itself has changed. While the base of the URL that is used remains the same, the first node of the URL is now your API token, the second node is the service that is called, and the third node is the configuration to use in the call. Query parameters are still added to the URL to instruct the system filter to apply and how to obtain the content to process.

To convert your version 1.0 API call to the new version, simply replace it with the following call:

   http://api.semantichacker.com/TOKEN/signature/odp_2006_l2_20k?filter=html

Any additional parameters you previously added to the call URL can be added to the new URL.

Changes to the API Request Parameters

In addition to the change in the URL, there were minor changes to the parameters that are supported in the call. Please review the following table to understand which parameters have changed. Also, review the Common Request Info to see the new parameters that are available.

Name Value Required Changes from the original API
token your API token Not Applicable No longer specified as a parameter. The token must now be included within the first part of the call URL.
uri a valid URI No No changes from the previous release
type 'html', 'text' or 'wp' No No longer supported. This parameter has been replaced by the filter parameter which is described in the Common Request Info page.
content content to process No No changes from the previous release.
showLabels 'true' or 'false' No No changes from the previous release.

Changes to the XML Response Format

The capabilities of the new API warranted the need to report additional information back to the caller and we have done so by providing an 'about' section at the beginning of each response. That, along with isolating the data provided by the service, required us to provide a new format for the response XML as follows:

  <?xml version="1.0" encoding="UTF-8" ?> 
   <response xmlns="http://www.semantichacker.com/api">
    <about>
       <requestId>A44A721C0F3B8CA4D7C07F3BA7ECE71B</requestId> 
      <docId>2B6B2F96D50E963ABAD3D2BE2E75B389</docId> 
       <systemType>signature</systemType> 
       <configId>odp_2006_l2_20k</configId> 
       <contentType>text/html</contentType> 
       <contentDigest>2B6B2F96D50E963ABAD3D2BE2E75B389</contentDigest> 
       <requestDate>2008-11-24T15:46:47+0000</requestDate> 
       <systemVersion>2.0</systemVersion> 
 </about>
   <siggen>
     <siggenResponse>
       <signature>
           <dimension label="Computers/Computer_Science/…" index="11011" weight="0.6952775" />
            ...
            ...
           <dimension label="Computers/…." index="11021" weight="0.4952775" />
       </signature>
    </siggenResponse>
 </siggen>
</response>