ESS_Bibliography_backend/api/README.api

ESS Bibliography API documentation
Version: 0.1

Further Info: May Dousak (may.dousak@fdv.uni-lj.si)

--------------------------------------------------------------------------------
1. GENERAL PRINCIPLES
2. LIST OF CALLS
--------------------------------------------------------------------------------
1. GENERAL PRINCIPLES

1.1 SENDING REQUESTS 

    Your client should request queries using a POST parameter to:

    a) API URL

        default: https://bibliography.europeansocialsurvey.org/api

    b) an appropriate command, passed as a POST variable w

    c) (optional) parameters as additional POST variables


1.2 RECEIVING RESPONSES

    In case of success, data is received along with HTTP code 200 ("OK").

    In case of wrong call, http code 400 ("Invalid request") is returned.

    In case of error in server side appropriate HTTP response code along with 
        text content is returned.

    In essence: check the response codes before reporting bugs!



1.3 JQUERY CLIENT EXAMPLE

    The following simple example requests the lists of countries and fills the 
    according drop-down ("affiliation"). 

        $.ajax ({
            method: "POST",
            url: API_URL,
            data: {
                w: 'list_countries'
            }
        })
        .done (function (msg) {
            if (msg == '') {
                console.log('No response received from API!');
            }
            else {
                $('#affiliation').html('<option value="0">Any</option>');

                if (msg['status'] == "200") {
                    msg['data'].forEach(function (item) {
                        $('#affiliation').html( $('#affiliation').html() + '<option value="' + item['id'] + '">' + item['name'] + '</option>');
                    });
                }
                else {
                    console.log(msg);
                }
            }
        })
        .fail (function() {
            console.log('No response received from API!');
        });


--------------------------------------------------------------------------------

2. LIST OF COMMANDS


    browse

        Displays list of entries based on the browse data
        
        Extra POST variables: 
            (in progress. Please refer to classes/browse.php)

        Response: json array of results.



    browse2spreadsheet

        Exports the current list of entries into a spreadsheet (CSV).
        
        Extra POST variables: 
            (in progress. Please refer to classes/browse.php)

        Response: CSV file.



    display_item

        Displays details for the selected item (from search_suggestions)

        Extra POST variables: 
            id - id of the item

        Response: array (
            name : item name
            label : item label
            block : block item resides in
            txt : item full text )        
   

    doi

        Fetches bibliographic data from DOI record. Please use sparingly as it
        connects to third-party servers (DOI) and we do not want to get blocked.

        Extra post varialbes: 
            doi : doi record

        Response: array containing citation data.



    item2spreadsheet

        Exports item citations into a spreadsheet

        Extra POST variables: 
            id: item id

        Response: CSV file.        
      
        
    item_citations

        Displays all the bibliographic entries "using" the selected item.

        Extra POST variables: 
            id: item id

        Response: json list of entries using the given item.



    list_countries

        returns list of countries (for which there are bibliographic entries) 
        you might want to use in a form for searching records.

        Extra POST variables: none
        Response: array(country_id => country_name)


    list_items

        returns list of ESS items you might want to use in a form for searching 
        records.

        Extra POST variables: none
        Response: array(item_id => item_name)


   list_journalField

        returns list of journal fields you might want to use in a form for 
        searching records.

        Extra POST variables: none
        Response: array(journal_id => journal_name)

    list_modules

        returns list of ESS modules you might want to use in a form for 
        searching records.

        Extra POST variables: none
        Response: array(module_id => module_name)


    list_pubType

        returns list of all publication types you might want to use in a form 
        for searching records.

        Extra POST variables: none
        Response: array(pubType_id => pubType_name)


    list_rounds

        returns list of ESS rounds you might want to use in a form for 
        searching records.

        Extra POST variables: none
        Response: array(round_id => round_name)


    list_topics

        returns list of ESS topics countries you might want to use in a form for
        searching records.

        Extra POST variables: none
        Response: array(topic_id => topic_name)


    search

        See search_suggestions.
        When fulltext is enabled, it will return list of all results.   

          
  
    search_suggestions

        returns list of search suggestions for fulltext search.
        Currently, it only works on item search (need to update it to fulltext)

        Extra POST variables: 
            txt - fulltext to search for

        Response: array (
            id : item ID
            name : item name
            label : item label
            block : block item resides in
            txt : item full text )        


    total_items_published

        Returns the number of records in the database.

        Extra POST variables: none
        Response: number of bibliographic entries (integer).