Pensoft Developers

The ARPHA Writing Tool provides a RESTful API for automated creation of AWT documents, which processes HTTP requests at https://arpha.pensoft.net/api.php. The API reports in XML format. All Pensoft users can use the API freely.

Authenticate

Tests that the specified user can be successfully authenticated to the system

Allowed HTTP methods:

POST with "Content-type" header set to "application/x-www-form-urlencoded"
GET

Required pameters:

action=authenticate
username=[username] Pensoft username of the user using the api
api_key=[api_key] API Key of the user using the API (this key is shown in "Account settings" in AWT)

Sample output:

A successful authentication result should look like this

<result>
	<requestId>1a00d71bd1</requestId>
	<returnCode>0</returnCode>
	<authentication_result>Authentication successful</authentication_result>
</result>

An unsuccessful authentication result should look like this. A description of the error is stored in the errorMsg node

<result>
	<requestId>a67870f997</requestId>
	<returnCode>1</returnCode>
	<errorCount>1</errorCount>
	<errorMsg>pwt.api.noSuchUser</errorMsg>
</result>

Request api key

Returns username and password associated api key

Allowed HTTP methods:

POST with "Content-type" header set to "application/x-www-form-urlencoded"
GET

Required pameters:

action=get_api_key
username=[username] Pensoft username of the user using the api
password=[password] Pensoft username's password using the api

Sample output:

A successful api key request result should look like this. An api key is returned in returnResult node.

<result>
	<requestId>1a00d71bd1</requestId>
	<returnCode>0</returnCode>
	<returnResult>xxx</returnResult>
</result>

An unsuccessful api key request should look like this. A description of the error is stored in the errorMsg node.

<result>
	<requestId>a67870f997</requestId>
	<returnCode>1</returnCode>
	<errorMsg>Wrong credentials</errorMsg>
	<fpassLink>[forgotten password link]</fpassLink>
</result>

fpassLink - link to forgotten password page

List available journals

Lists all the available journals in which documents can be created.
No credentials are required for this method

Allowed HTTP methods:

POST with "Content-type" header set to "application/x-www-form-urlencoded"
GET

Required pameters:

action=list_journals

Sample output:

<result>
	<requestId>9ed1b0e546</requestId>
	<returnCode>0</returnCode>
	<journals>
		<journal>
			<full_name>Biodiversity Data Journal</full_name>
			<name>bdj</name>
		</journal>
	</journals>
</result>

A list of all the available journals is returned. Each journal has the following fields:

full_name - the full name of the journal. This value is used in the document xml when creating new documents
url_name - the url name of the journal. This value is used when querying all the available article types for the journal

List available journal article types

Lists all the available article types for the specified journal.
No credentials are required for this method

Allowed HTTP methods:

POST with "Content-type" header set to "application/x-www-form-urlencoded"
GET

Required pameters:

action=list_journal_papertypes
journal_name=[journal_url_name] - the url name of the journal as returned from the List available journals method

Sample output:

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <requestId>9d8ef5c0d9</requestId>
  <returnCode>0</returnCode>
  <papertypes>
    <papertype>
      <name>Short Communication</name>
      <good_for>Short Communication</good_for>
      <description>Short Communication</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/Short Communication</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/Short Communication</example_documents_url>
      <example_published_documents_url>/examples.php?id=107</example_published_documents_url>
    </papertype>
    <papertype>
      <name>R Package</name>
      <good_for>R Package</good_for>
      <description>Description of an R Package including information on its purpose, installation and usage.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/r_package</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/r_package</example_documents_url>
      <example_published_documents_url>/examples.php?id=101</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Software Description</name>
      <good_for>Software Description</good_for>
      <description>Description of software tools to provide published record and citation.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/software_description</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/software_description</example_documents_url>
      <example_published_documents_url>http://bdj.pensoft.net/browse_journal_articles.php?journal_name=bdj&amp;form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;section_type%5B%5D=14</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Forum Paper</name>
      <good_for>Forum Paper</good_for>
      <description>Publication meant to initiate a discussion on a particular scientific topic.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/forum_paper_(free_text_template)</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/forum_paper_(free_text_template)</example_documents_url>
      <example_published_documents_url>/examples.php?id=98</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Taxonomic Paper</name>
      <good_for>Taxonomic Paper</good_for>
      <description>An article that contains more comprehensive taxonomic results (e.g., taxonomic review or revision or several nomenclatural and taxonomic novelties). It must contain at least two taxon treatments, and/or checklists, and/or identification keys.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/taxonomic_paper</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/taxonomic_paper</example_documents_url>
      <example_published_documents_url>http://bdj.pensoft.net/browse_journal_articles.php?journal_name=bdj&amp;form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;section_type%5B%5D=3</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Single Taxon Treatment</name>
      <good_for>Single Taxon Treatment&#13;
</good_for>
      <description>Publication of a single new taxon, new synonym, change in taxonomic status, re-description, biological / ecological observations on a single species, and others.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/single_taxon_treatment</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/single_taxon_treatment</example_documents_url>
      <example_published_documents_url>/examples.php?id=71&#13;</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Interactive Key</name>
      <good_for>Interactive Key</good_for>
      <description>Online interactive identification key of a given higher taxon or species group. Contains a link to an openly accessible described online key.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/interactive_key</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/interactive_key</example_documents_url>
      <example_published_documents_url>http://bdj.pensoft.net/browse_journal_articles.php?journal_name=bdj&amp;form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;section_type%5B%5D=9</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Data Paper (Biosciences)</name>
      <good_for>Data Paper (Biosciences)</good_for>
      <description>Description of large datasets. Should contain a link to openly accessible described data. Alternatively, datasets can be uploaded and published as supplementary files.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/data_paper</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/data_paper</example_documents_url>
      <example_published_documents_url>http://bdj.pensoft.net/browse_journal_articles.php?journal_name=bdj&amp;form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;section_type%5B%5D=8</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Editorial </name>
      <good_for>Editorial </good_for>
      <description>Opinion article written by the senior editorial staff. </description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/editorial</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/editorial</example_documents_url>
      <example_published_documents_url>/examples.php?id=37</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Corrigendum</name>
      <good_for>Corrigendum</good_for>
      <description>A correction of an error or a list of errors discovered in a research after publication.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/corrigendum</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/corrigendum</example_documents_url>
      <example_published_documents_url>/examples.php?id=39</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Species Conservation Profiles</name>
      <good_for>Species Conservation Profiles</good_for>
      <description>A single or multiple IUCN species assessment report/s imported and edited in an IUCN-compliant species template.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/species_conservation_profiles</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/species_conservation_profiles</example_documents_url>
      <example_published_documents_url>/examples.php?id=100</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Methods</name>
      <good_for>Methods</good_for>
      <description>Description of the experiments and their rationale used for a research outcome to be concluded and verified.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/methods_(free_text_template)</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/methods_(free_text_template)</example_documents_url>
      <example_published_documents_url>/examples.php?id=65</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Research Article</name>
      <good_for>Research Article</good_for>
      <description>Publication of a study concluding significant new and original information.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/research_article_(free_text_template)</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/research_article_(free_text_template)</example_documents_url>
      <example_published_documents_url>/examples.php?id=68</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Alien Species Profile</name>
      <good_for>Alien Species Profile</good_for>
      <description>Assessment report of alien or invasive species following an IUCN-compliant species template. After publication, the article can be exported to the Global Invasive Species Database (GISD).</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/alien_species_profile</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/alien_species_profile</example_documents_url>
      <example_published_documents_url>/examples.php?id=89</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Commentary</name>
      <good_for>Commentary</good_for>
      <description>Short free-text publication meant to draw attention or criticise a previously published work. Does not include original data.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/commentary_(free_text_template)</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/commentary_(free_text_template)</example_documents_url>
      <example_published_documents_url>/examples.php?id=97</example_published_documents_url>
    </papertype>
  </papertypes>
</result>

A list of all the available article types for the specified journal:

name - the full name of the article type. This value is used in the document xml when creating new documents
good_for - a short list of all use cases of the article type
description - a short description of the article type
schema_url - a url where the XSD XML Schema (version 1.0) used to validate the documents of this type is available
example_documents_url - a url where example xml documents for this article type are available.
Special note - this documents have had their authors removed. In order to import them successfully you will have to specify authors.
example_published_documents_url - a url where published documents from this type can be viewed

Validate document

Validates the specified xml document against the schema corresponding to the document's article type
No credentials are required for this method

Allowed HTTP methods:

POST with "Content-type" header set to "application/x-www-form-urlencoded"

Required pameters:

action=validate_document
xml=[document_xml_content] - a string containing the xml of the document

Notes about the document structure and constraints:

The xml schema for each article type follows closely the structure of the documents for the specified type in the AWT. If you have any questions about a specific element you may create a new document in the tool and inspect the element there.
There must be exactly one author marked as submitting author by specifying a value of 1 in the following node:
document/objects/article_metadata/title_and_authors/author/fields/submitting_author/value
There are 3 types of figures in the AWT - images, plates and videos. Additionally there are 4 different plate types. For more info on figures/plate types view the figures section in any document in the AWT.
Image figures, and plate parts have an image_url field which should contain a url to the respective image. When creating the image/plate part the image will be downloaded from this url. If this attribute is specified and the url is not available an error will occur during import.
Supplementary files have a suppl_file_url field which should contain a url to the respective supplementary file. When creating the supplementary file the resource will be downloaded from this url. If this attribute is specified and the url is not available an error will occur during import.
All citable elements (i.e figures, plate parts, suppl. files, references) should have unique id attributes
The api allows importing of citations. They are stored as children of the /document/citations element in the document xml. Each citation has the following format: <citation id="6"> <citation_type>tables</citation_type> <object_id>42</object_id> <object_id>43</object_id> </citation> Notes about the format:
- citation id attrbibute - the unique id of the citation. This id is used when referring the citation in the text where it occurs. The citation is referred in the text with the inline_citation element which only has a citation_id attribute. An example of introduction section where the specified citation is citated may look like this: <introduction> <fields> <introduction> <value> <p> Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed <inline_citation citation_id="6" /> diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. Nam liber tempor cum soluta nobis eleifend option congue nihil imperdiet doming id quod mazim placerat facer possim assum. Typi non habent claritatem insitam; est usus legentis in iis qui facit eorum claritatem. Investigationes demonstraverunt lectores legere me lius quod ii legunt saepius. Claritas est etiam processus dynamicus, qui sequitur mutationem consuetudium lectorum. Mirum est notare quam littera gothica, quam nunc putamus parum claram, anteposuerit litterarum formas humanitatis per seacula quarta decima et quinta decima. Eodem modo typi, qui nunc nobis videntur parum clari, fiant sollemnes in futurum. </p> </value> </introduction> </fields> </introduction>
- citation_type - the type of the citation. The allowed values are
  - figs - a citation of figures
  - tables - a citation of tables
  - references - a citation of references
  - sup files - a citation of supplementary files
- multiple object_id elements. Each element stores the id attribute of the citated element. (i.e figure, plate part, suppl. file, reference). Each id should be a 1-based number (e.g. 1, 2, etc.)

Sample output:

A successful validation result should look like this

<result>
	<requestId>558c037d61</requestId>
	<returnCode>0</returnCode>
	<validation_result>Document validated successfully</validation_result>
</result>

An unsuccessful validation result will look like this. A description of the error is stored in the errorMsg node

<result>
	<requestId>4b4195735c</requestId>
	<returnCode>1</returnCode>
	<errorCount>1</errorCount>
	<errorMsg>Xml is invalid!Fatal Error 76: Opening and ending tag mismatch: aut1hor line 17 and author on line 57</errorMsg>
</result>

Import document

Imports the document in the system. Before importing the document, user authentication and document validation are executed. If either one fails an error will occur.

Allowed HTTP methods:

POST with "Content-type" header set to "application/x-www-form-urlencoded"

Required pameters:

username=[username] Pensoft username of the user using the api.
N.B. This user may be different to the submitting author of the imported document
api_key=[api_key] API Key of the user using the API (this key is shown in "Account settings" in AWT)
action=import_document
xml=[document_xml_content] - a string containing the xml of the document

Notes:

N.B. After a successful import only the users added as authors in the document's xml will be able to see the document on their dashboard and edit it (i.e. if the user running the API is not added as author of the document they won't be able to see the document or access the document link returned from the API).

Sample output:

A successful import result should look like this

<result>
	<requestId>edbd3be071</requestId>
	<returnCode>0</returnCode>
	<document_id>123456</document_id>
	<document_link>http://arpha.pensoft.net/display_document.php?document_id=123456</document_link>
	<document_autologin_link>[auto login link]</document_autologin_link>
</result>

document_id - the id of the newly imported document
document_link - a url in the AWT where the imported document can be edited further
document_autologin_link - an autologin url of the user using the api in the AWT where the imported document can be edited further

An unsuccessful import result will look like this. A description of the error is stored in the errorMsg node

<result>
	<requestId>4b4195735c</requestId>
	<returnCode>1</returnCode>
	<errorCount>1</errorCount>
	<errorMsg>Xml is invalid!Fatal Error 76: Opening and ending tag mismatch: aut1hor line 17 and author on line 57</errorMsg>
</result>

ARPHA Writing Tool (AWT) API

Feedback is welcome via

API Methods

Authenticate

Allowed HTTP methods:

Required pameters:

Sample output:

Request api key

Allowed HTTP methods:

Required pameters:

Sample output:

List available journals

Allowed HTTP methods:

Required pameters:

Sample output:

List available journal article types

Allowed HTTP methods:

Required pameters:

Sample output:

Validate document

Allowed HTTP methods:

Required pameters:

Notes about the document structure and constraints:

Sample output:

Import document

Allowed HTTP methods:

Required pameters:

Notes:

Sample output: