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>91b924ce36</requestId>
  <returnCode>0</returnCode>
  <papertypes>
    <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.&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/browse_journal_articles.php?form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;search_in_=0&amp;section_type%5B%5D=295"&gt;See published papers with this template&lt;/a&gt;</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>Short Communication</name>
      <good_for>Short Communication</good_for>
      <description>Short articles (usually 3-4 pages) addressing preliminary findings of higher interest, unique approaches, controversial opinions, new methods or innovative technologies etc. that demand fast publication.</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>Software Description</name>
      <good_for>Software Description</good_for>
      <description>Description of software or an online tool or platform that contains a link to the openly accessible code of the described tool.&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="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"&gt;See published papers with this template&lt;/a&gt;</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>/examples.php?id=20</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Forum Paper</name>
      <good_for>Forum Paper</good_for>
      <description>Publication meant to initiate or respond to participate in 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>Taxonomy &amp; Inventories</name>
      <good_for>Taxonomy &amp; Inventories</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.&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="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"&gt;See published papers with this template&lt;/a&gt;</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>/examples.php?id=16</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 that contains a link to the openly accessible online key. &lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/browse_journal_articles.php?form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;search_in_=0&amp;section_type%5B%5D=9"&gt;See published papers with this template&lt;/a&gt;</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>/examples.php?id=18</example_published_documents_url>
    </papertype>
    <papertype>
      <name>Data Paper (Biosciences)</name>
      <good_for>Data Paper (Biosciences)</good_for>
      <description>Formal paper describing large datasets. The article should contain a link to the openly accessible dataset  deposited in an internationally recognised repository (see instructions and list of recommended repositories in the &lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/about#Datapublication"&gt;Data Publishing Guidelines&lt;/a&gt;).&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="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"&gt;See published papers with this template&lt;/a&gt;</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>/examples.php?id=19</example_published_documents_url>
    </papertype>
    <papertype>
      <name>OMIC Data Paper</name>
      <good_for>OMICS Data Paper</good_for>
      <description>Description of omics data that can include information about the genome ((meta)genomics), transcription products ((meta)transcriptomics), protein products ((meta)proteomics), and metabolic products ((meta)metabolomics). More information can be found &lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/about#OmicsDataPapers"&gt;here&lt;/a&gt;.</description>
      <schema_url>https://arpha.pensoft.net/dev/xsd/omic_data_paper</schema_url>
      <example_documents_url>https://arpha.pensoft.net/dev/example/omic_data_paper</example_documents_url>
      <example_published_documents_url>/examples.php?id=113</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.&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/browse_journal_articles.php?form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;search_in_=0&amp;section_type%5B%5D=294"&gt;See published papers with this template&lt;/a&gt; </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 novel methodologies and methods used in biodiversity research and biodiversity informatics.&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/browse_journal_articles.php?form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;search_in_=0&amp;section_type%5B%5D=261"&gt;See published papers with this template&lt;/a&gt; </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 presenting significant new and original information.&lt;br/&gt;&lt;br/&gt;
&lt;b&gt;NOTE&lt;/b&gt;: For submissions to the &lt;b&gt;Biodiversity Data Journal&lt;/b&gt; containing taxonomic, nomenclatural, faunistic or floristic data, &lt;br/&gt;please use the “Taxonomic paper” template.</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 integrated with the Global Invasive Species Database (GISD).&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/browse_journal_articles.php?form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;search_in_=0&amp;section_type%5B%5D=435"&gt;See published papers with this template&lt;/a&gt;
</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. It does not include original data.&lt;br/&gt;&lt;br/&gt;&lt;a style="color:#73cdd9; text-decoration: none;" href="https://bdj.pensoft.net/browse_journal_articles.php?form_name=filter_articles&amp;sortby=0&amp;journal_id=1&amp;search_in_=0&amp;section_type%5B%5D=397"&gt;See published papers with this template&lt;/a&gt;</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: