<commit_before>{% extends "developers/devbase.html" %}
{% block content %}
<div class="row-fluid">
    <div class="span12">
        <p>API docs here, once complete</p>
    </div>
</div>
{% endblock %}<commit_msg>updated the api template with the content of the API doc<commit_after>{% extends "developers/devbase.html" %}
{% block content %}
<div class="row-fluid">
    <div class="span12">

<span class="hero-unit">
    <h1>IsItOpenAccess API Documentation</h1>
</span>

<p>This document contains the specification discussions for the IIOA API</p>


<h2>Lookup Endpoint</h2>


<p>Use this endpoint to find the licensing conditions of articles identified by either DOI or PMID.</p>

<ul style="list-style-type:none;">
    <li>POST /lookup</li>
    <li>GET / lookup</li>
    <li>GET /lookup/ID1</li>
    <li>GET /lookup/ID1,IDn where IDx are strings</li>
</ul>

<p>Maximum number of allowed IDs is 1000. Frontend will abort with 400 if longer thatn 1000.</p>

<p>For GET, conneg for HTML or JSON. HTML shows a simple web page to accept query params to build a query.</p>

<code><pre>
    GET /lookup/12345,67890 HTTP/1.1
    Accept: application/json
</pre></code>

<p>For POST, expected data is either a JSON list of BibJSON (http://bibjson.org) identifier objects, or a simple list of identifiers if no more is known about them:</p>

<code><pre>
    [
        10.1234/1389849..., 
        14754839, 10.....
    ]
</pre></code>

<p>or</p>

<code><pre>
    [
	    {
            "id":".......",
		    "type":"......if known"
	    }
    ]
</pre></code>

<p>The "type" parameter MUST be either "doi" or "pmid" or the identifier will not be recognised.</p>

<p>Both GET and POST respond properly to JSONP requests.</p>

<p>If a simple list of identifiers is provided, IIOA will attempt to determine if they are DOIs or PMIDs, and interpret them accordingly.  If it cannot identify the type it will not be able to determine their status.</p>

<p>Both POST and GET, when asked for JSON, respond with an object as follows:</p>

<code><pre>
    {
	    "requested": NUMBER_REQUESTED,
	    "results": [
		    {BIBJSON_RECORD}, ...
	    ],
	    "errors":[
		    {
		        "identifer" : BIBJSON_IDENTIFIER_OBJECT, 
                "error" : "...description..."
            },
            ...
	    ],
	    "processing":[
		    {
		        "identifier" : BIBJSON_IDENTIFIER_OBJECT
		    },
		    ...
	    ]
    }
</pre></code>

<ul style="list-style-type:none;">
    <li>requested - The number of ids requested by the client</li>
    <li>results - a list of BibJSON records for all items that IIOA knows the licensing conditions for already</li>
    <li>errors - a list of the identifier records that represent the original identifiers provided by the client which IIOA was unable to process for any one of a variety of reasons.  The "error" key in the resulting object contains a text description of the reason for failure.</li>
    <li>processing - a list of the identifier records that represent the original identifiers provided by the client which IIOA is currently processing.</li>
</ul>

<p>When the client receives its first response from IIOA it is likely that many items will be in the "processing" queue.  IIOA will lookup the licence conditions for these items as quickly as possible and have them ready to make available, but it will not notify the client.  The recommended mode of usage is for the client to poll either its original request URL, or the URLs of all of the items in the "processing" queue, in order to retrieve updates.  IIOA does not guarantee a particular timescale upon which licence information will be available.</p>


<h2>Query Endpoint</h2>


<p>Use this endpoint to search the current knowledge of the IIOA database.</p>

<ul style="list-style-type:none;">
    <li>GET /query</li>
    <li>POST /query</li>
</ul>

<p>This is a search endpoint which responds to <a target="_blank" href="http://elasticsearch.org">Elasticsearch</a> query strings.  The structure of the BibJSON objects stored in the index is detailed below, and can be used as a reference to build search strings.</p>

<p>This endpoint only searches what IIOA already knows - it will make not trigger an attempt to lookup a licence (use the Lookup Endpoint for this).</p>

<p>This endpoint only accepts and responds with JSON, and responds properly to JSONP requests.</p>


<h2>IIOA BibJSON record</h2>


<p>An IIOA formatted <a target="_blank" href="http://bibjson.org">BibJSON</a> record will have some or all of the fields laid out in the example below.</p>

<code><pre>
    {
        "title": "Open Bibliography for Science, Technology and Medicine",
        "author":[
            {"name": "<NAME>"},
            {"name": "<NAME>"},
            ...
        ],
        "year": "2011",
        "journal": {"name": "Journal of Cheminformatics"},
        "link": [{"url":"http://www.jcheminf.com/content/3/1/47"}],
        "identifier": [
            {
                "type":"doi",
                "id":"10.1186/1758-2946-3-47"
                "canonical":"doi:10.1186/1758-2946-3-47"
            }
        ],
        "license": [
            {
                "status": "active",
                "maintainer": "",
                "description": "",
                "family": ""
                "title": "Creative Commons Attribution",
                "domain_data": true/false,
                "url": "http://www.opendefinition.org/licenses/cc-by",                
                "version": "", 
                "domain_content": true/false,
                "is_okd_compliant": true/false,
                "is_osi_compliant": true/false,
                "domain_software": true/false,
                "type": "cc-by",
                "jurisdiction": "",
                "open_access": true/false,
                "BY": true/false,
                "NC": true/false,
                "ND": true/false,
                "SA": true/false,

                "provenance": {
                    "category": "page_scrape",
                    "description": "how the content was acquired ...",
                    "agent": "IsItOpenAccess Service/0.1 alpha",
                    "source": "http://www.plosbiology.org/article/info%3Adoi%2F10...",
                    "date": "2013-02-16T21:51:54.669040"
                }

            }
        ]
    }
</pre></code>

<p>Note that the IIOA BibJSON records will often have sparse to non-existant bibliographic metadata.  If you want bibliographic metadata you should look to a service such as CrossRef.</p>

<ul style="list-style-type:none;">
    <li>identifier - the list of identifiers in the BibJSON record will contain at least one which has your originally requested ID.</li>

    <li>license - (note the US spelling) the list of licenses seen for this item.  A record may contain an arbitrary number of licence records, but the client should only present to an end user the most recent licence statement as being the definitive one.  Licence statements are expressions of the Open Definition of the known licence (see http://opendefinition.org/licenses/)</li>

    <li>license/open_access - boolean indicating whether the IIOA service considers this licence to be "Open Access".</li>

    <li>license/BY - boolean indicating whether the licensing conditions for this item require Attribution (e.g. CC-BY)</li>

    <li>license/NC - boolean indicating whether the licensing conditions for this item stipulate a Non Commercial clause (e.g. CC-NC)</li>

    <li>license/ND - boolean indicating whether the licensing conditions for this item indicate that No Derivatives are allowed (e.g. CC-ND)</li>

    <li>license/SA - boolean indicating whether the licensing conditions for this item require that any derivative works are Share Alike (e.g. CC-SA)</li>
     
    <li>license/provenance - Contains information about how this particular license statement was obtained.</li>

    <li>license/provenance/category - the type of acquisition process that was used to acquire the license information. Should be one of:
        <ul>
            <li>page_scrape - the content was scraped from an HTML page</li>
            <li>xml_api</li>
        </ul>
    </li>

    <li>license/provenance/date - the date that this licence was acquired.  This is the field that developers should use to determine the most recent licence record, which is considered by IIOA to be the current licence conditions of the item.</li>
    
</ul>


    </div>
</div>
{% endblock %}
{'fraction_non_alphanumeric': 0.1139926912648827, 'fraction_numerical': 0.015089001532476718, 'mean_word_length': 2.5918712955122776, 'pattern_counts': {'":': 45, '<': 137, '<?xml version=': 0, '>': 137, 'https://': 0, 'lorem ipsum': 0, 'www.': 3, 'xml': 1}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '403784', 'n_tokens_mistral': 2580, 'n_tokens_neox': 2332, 'n_words': 925}