OAPS Webservice API

To use OAPS within publication and conference management systems, we offer an easy to use API for automatic use of our service. This API is based on SOAP and all data is encapsulated into XML messages. At the moment the API offers only functions for the plagiarism search but not for user management. The corresponding WSDL file of the OAPS API can be found at:

http://oaps.eu/api/oaps.wsdl

The WSDL file as well as all API functions are available both via HTTP and HTTPS. As the plagiarism check for a single document may take some time we used a stateless and asynchronous design for our API. This means that you should submit one or several documents to OAPS and afterwards fetch the corresponding reports by polling the API. You will find further details below.

Usage

If you would like to use our API, please feel free to contact us at info@oaps.eu, as the usage is restricted to only those accounts that were administratively activated for the API.

Authentication

The OAPS API can only be used with user accounts that are activated for the use of the API. Therefore, each SOAP request must contain the following authentication information:

API Functions

startJob

By the use of this function a new document is placed into the corresponding user account and the plagiarism search is started.

Signature

jobid = startJob(login, data, lang)

Parameter

login - Authentication information consisting of user name and md5-hash of the password

data - The document that should be checked as base64 encoded data

lang - The language of the report to be produced - possible values:

  • de - for a German report
  • en - for an English report
  • fr - for a French report

Return

jobid - Alphanumeric value that identifies the newly created job

getReport

This function can be used to fetch a report. The corresponding job needs to be identified by the given jobid. Any report that was retrieved correctly from the OAPS API (status==OK or status==ERROR) should be deleted from the OAPS server afterwards by using the deleteJob function (see below).

Signature

(jobid, status, rating, file) = getReport(login, jobid)

Parameter

login - Authentication information consisting of user name and md5-hash of the password

jobid - Alphanumeric value that identifies the job

Return

A complex data type containing the following fields is returned:

jobid - Alphanumeric value that identifies the job

status - Status of the job. Possible values are:

  • OK - The job was finished correctly. The report is contained in the field named file
  • ERROR - The job could not be finished correctly and no report was created.
  • PROCESSING - The job is still running. You should check again later.

rating - The rating of the document which is the fraction of searched and found text fragments. If the job is still running or could not be finished correctly this value is NULL.

file - The created report in HTML format and base64 encoded. If the job is still running or could not be finished correctly this value is NULL.

getNextReport

This function can be used to fetch the report of the next finished job. Compared to the getReport function, no jobid needs to be given. If there are several jobs currently processed by OAPS one single call of getNextReport is sufficient to retrieve the next available report. Each time a report is retrieved successfully from OAPS (status==OK or status==ERROR) it should be deleted by using the deleteJob function (see below).

Signature

(jobid, status, rating, file) = getNextReport(login)

Parameter

login - Authentication information consisting of user name and md5-hash of the password

Return

If there is no finished report available, NULL is returned. Otherwise a complex data type containing the following fields is returned:

jobid - Alphanumeric value that identifies the job

status - Status of the job. Possible values are:

  • OK - The job was finished correctly. The report is contained in the field named file
  • ERROR - The job could not be finished correctly and no report was created.

rating - The rating of the document which is the fraction of searched and found text fragments. If the job is still running or could not be finished correctly this value is NULL.

file - The created report in HTML format and base64 encoded. If the job is still running or could not be finished correctly this value is NULL.

deleteJob

This function can be used to delete a job completely from the system. Each job that was created by the use of the startJob function should be deleted from the system after it is finished and the report was successfully retrieved from the system. Jobs that produced an error needs to be deleted as well.

Signature

deleted = deleteJob(login, jobid)

Parameter

login - Authentication information consisting of user name and md5-hash of the password

jobid - Alphanumeric value that identifies the job

Rückgabewert

deleted - True in case of success and false otherwise

PHP Code

For the use of this SOAP API from any PHP code we have created an easy to use example implementation: oapsAPI.php.gz

The PHP class OapsAPI needs the corresponding authentication information in the constructor and provides a corresponding function for each API function.