Manuals, Tutorials, and More

Home > iThenticate > iThenticate API Guide > Introduction

Introduction

This document is a technical reference specification for the iThenticate API. The API is based on the XML-RPC specification which may be referenced at http://xmlrpc.com. The xml examples shown in this document have added white space for readability.

 

To begin using the API you will need an account username and password to access the API. See your iThenticate account representative to obtain these credentials.

 

The url of the API resource is https://api.ithenticate.com/rpc (note that there is no trailing slash).

 

An example API client written in Perl is available as a guide and can be provided by your account representative. A number of XML-RPC client libraries exist for various programming languages. These libraries typically provide a high-level interface for making XML-RPC requests. Some examples below will show the raw XML request and response “payload”, but client libraries often allow you to work with your language’s familiar data structures directly and not with the raw XML.

 

The XML examples shown in this document have added white space for readability.

API Constraints

 

API requests are throttled to 60 requests/second per account. A user’s account can not have more than 1000 folders and 100 folder groups. All XML-RPC data must be UTF-8 encoded. All requests are made via the HTTP POST method. All connections to the iThenticate API server must be made via an SSL connection via https. Requests made over http will be returned a 302 redirect code, which some XML-RPC clients may not handle appropriately.

API Requests

 

Requests are sent in accordance with the XML-RPC specification (http://www.xmlrpc.com/). An XML-RPC “struct” element is used as the payload container for all iThenticate XML-RPC requests. This allows named parameters as input data. The order of the members within the struct element is not important.

 

Every API request must be encrypted via Secure Sockets Layer (SSL).

 

Every API request must include a session id (sid). The session id is obtained by an initial “login” API request that returns the session id in the XML-RPC response.

 

The iThenticate API will request validation but the user is encouraged to ensure that client side requests conform to the guidelines presented in the API. Requests which do not conform to the parameters and examples shown in this document cannot be guaranteed to return correct responses, nor can they be guaranteed to return errors or messages about what elements of the request were invalid. As with HTTP requests,request parameters that are not designated for a certain method will be ignored rather than an error being thrown. See each method description for the required request parameters.

 

An example login request is shown here (white space inserted for readability). The username and password are passed in a struct element.

 

<?xml version=”1.0” encoding=”UTF-8”?>
<methodCall>
     <methodName>login</methodName>
         <params>
             <param>
                 <value>
                     <struct>
                         <member>
                             <name>password</name>
                             <value><string>api_test_user_123</string></value>
                             </member>
                             <member>
                         <name>username</name>
              <value><string>api_test_user@test.api.ithenticate.com</string></value>
                 </member>
             </struct>
         </value>
     </param>
 </params>
</methodCall>

API Responses

 

Responses are returned in accordance with the XML-RPC specification (http://www. xmlrpc.com/). An example successful login response is shown below. The session id used to authenticate subsequent requests is returned in the sid element.

 

All responses include a api_status value, which may have the following values. The values use coding scheme similar to the familiar HTTP status codes.

 

Note: Note: the api_status is NOT the HTTP status for your request

 

200 - successful response, repsonse may contain messages but not errors

401 - request failed to provide an authenticated session id (sid) for the resource

403 - access to the requested resource is not authorized

404 - requested resource was not found

500 - error in the request, response payload may contain errors or messages

The date and time format for any response data is dateTime.iso8601.

 

An example of a successful response from a login method request: 

 

<struct>
 <member>
     <name>sid</name>
     <value><string>7c306332c88eab2842d83fe099585fceb2cd1e34</string></value>
 </member>
 <member>
     <name>api_status</name>
     <value><int>200</int></value>
 </member>
</struct>

Failed Responses 

 

Responses can contain a list of one or more errors. These are strings describing the error condition. These are typically due to input data validation failures and thus associated with the specific input field.

 

Below is an example of a response from a failed login method call where the password field was too short:

 

<struct>
     <member>
         <name>errors</name>
         <value>
             <struct>
                 <member>
                     <name>password</name>
                     <value>
                         <array><data>
                         <value><string>Input must be at least 6 characters. You submitted 3</string></value>
                         </data></array>
                     </value>
                 </member>
             </struct>
         </value>
     </member>
     <member>
         <name>api_status</name>
         <value><int>500</int></value>
     </member>
</struct>

 

Note: These error messages may be localized based on the account’s language preferences.

Response Messages

 

Responses can also contain a list of one or more “messages”. These are typically informational such as “record updated”, but may also include error information about a failed request.

 

Below is an example response for a successful folder creation containing informational status message:

 

<struct>
     <member>
         <name>sid</name>
             <value><string>374cfed6020ff134e36263e8c070a47aba50a757</string></value>
     </member>
     <member>
         <name>messages</name>
         <value><array><data>
         <value><string>Folder Group Created</string></value>
         </data></array></value>
     </member>
     <member>
         <name>api_status</name>
         <value><int>200</int></value>
     </member>
     <member>
         <name>id</name>
         <value><int>109</int></value>
     </member>
</struct>

Error Processing

 

XML-RPC is an HTTP-based protocol, and thus any client applications must look at the HTTP status code before attempting to parse the XML response. iThenticate API requests return 200 HTTP status code unless there is a serious error that prevents processing of the request. For example, attempting to contact the API with an invalid XML-RPC endpoint URL will result in a HTTP status code 404. Malformed XML-RPC requests (e.g. invalid XML) will likely generate a 500 HTTP status code.

 

The iThenticate XML-RPC response will include an api_status element that indicates the success or failure of the API request. The api_status for normal successful methods will be 200. Although the api_status code is similar to canonical HTTP responses code, they should not be considered the same. Differences between values for api_status and standardized HTTP response codes in the HTTP may be subtle and the user should remember that HTTP status codes and api_status are separate entities and will almost always have different values for responses. Clients should check the HTTP response code before looking at the api_status value returned in the XML-RPC response.

 

An api_status code of 401 is returned for authorization failures. This can be due to invalid login credentials or a request coming from an IP address not authorized for API requests.

 

An api_status code of 403 indicates that the user does not have access to the requested resource.

 

An api_status code of 404 indicates that an object id in the response does not exist or is invalid.

 

An api_status code of 500 indicates that the request was invalid in some way. This would typically be if the data passed in the XML-RPC request did not meet the requirements of the method. For example, not providing required elements in the XML-RPC request or submitting incorrectly formatted data.

 

Additional information about an error can be obtained by inspecting two additional elements other than the api_status element.

 

As described above, the XML-RPC response may include a messages element. This element may provide an overall reason for the failure, for example “Failed to log in”, or a specific failure condition not covered by the errors field.

 

The distinction between the errors and the messages elements may not be entirely clear to the end user. In the case where the documentation is unclear, the user is advised to discern the exact behavior of each element from the response given by the API web service itself.

 

Example of a response that includes an error condition with a explanation in the messages element:

 

<?xml version=”1.0” encoding=”utf-8”?>
<methodResponse>
 <params>
     <param>
         <value>
             <struct>
             <member>
                 <name>messages</name>
                 <value>
                    <array>
                         <data>
                             <value>
                                 <string>Sorry, failed to log in.</string>
                             </value>
                         </data>
                     </array>
                 </value>
             </member>
 <member>
     <name>api_status</name>
         <value>
             <int>401</int>
         </value>
 </member>
             </struct>
         </value>
     </param>
 </params>
</methodResponse>

 

The message list may contain more than one message. For example, in this case more detail is provided about the error condition:

 

<?xml version=”1.0” encoding=”utf-8”?>
<methodResponse>
 <params>
    <param>
         <value>
             <struct>
             <member>
             <name>messages</name>
                 <value>
                 <array>
                 <data>
                     <value>
                     <string>Access denied from 127.0.0.1</string>
                     </value>
                 <value>
                     <string>Sorry, failed to log in.</string>
                 </value>
                 </data>
             </array>
         </value>
         </member>
 <member>
         <name>api_status</name>
         <value>
         <int>401</int>
         </value>
 </member>
         </struct>
     </value>
     </param>
 </params>
</methodResponse>

 

iThenticate API requests require one or more parameters. For example, logging in requires two parameters: a username and a password. The errors element, if included in the XML-RPC response, will provide details about errors with these parameters. The errors element is an XML-RPC struct element with the keys being the names of the parameters, and the values an XML-RPC list of one or more messages related to that parameter. The messages element may also contain details about errors encountered during the login process.

 

An example of the login method above shows an XML-RPC response where an invalid password parameter was submitted.

 

The following example shows an XML-RPC response that includes two messages, One begins with a generic message saying login did not succeed, and another message gives the reason for the failed login attempt.

 

<?xml version=”1.0” encoding=”utf-8”?>
<methodResponse>
 <params>
     <param>
         <value>
             <struct>
             <member>
             <name>messages</name>
                 <value>
                 <array>
                 <data>
                     <value>
                     <string>Access denied from 127.0.0.1</string>
                     </value>
                     <value>
                     <string>Sorry, failed to log in.</string>
                     </value>
                 </data>
                 </array>
                 </value>
             </member>
 <member>
     <name>status</name>
     <value>
     <int>401</int>
     </value>
 </member>
             </struct>
         </value>
     </param>
 </params>
</methodResponse>

 

You must to post a comment.
Last modified
09:14, 23 May 2017

Tags

This page has no custom tags.

Classifications

(not set)