INGe REST API Documentation

From MPDLMediaWiki
Jump to: navigation, search

The RESTRepresentational State Transfer APIApplication Programming Interface is reachable under {base_url}/rest/{endpoint}
To get an overview over all endpoints you can call {base_url}/rest/swagger-ui.html - Be aware that the examples are not correct!

The documentation will lead u through all the endpoints available in INGeInfrastructure Next Generation

Required fields are marked with *

LOGIN - {base_url}

User authentication

POST {base_url}/login

Login with your credentials

HEADER
"Content-Type" - text/plain
BODY
{your_login_name}:{your_password}
CURL EXAMPLE
curl -X POST "https://dev.inge.mpdl.mpg.de/rest/login" -H 'Content-Type: text/plain' -d 
'{your_login_name}:{your_password}'


GET {base_url}/logout

HEADER
* "Authorization" - authorization token
CURL EXAMPLE
curl -X GET "https://dev.inge.mpdl.mpg.de/rest/login" -H "Authorization: {your_token_from_login}"


ITEMS - {base_url}/rest/items

GET {base_url}/rest/items/{publication_id}

Retrieve one single publication with a specific id

HEADER
"Authorization" - authorization token
PARAMETER
-
CURL EXAMPLE
curl -X GET "https://dev.inge.mpdl.mpg.de/rest/items/item_123" -H "Authorization: {your_token_from_login}"


GET {base_url}/rest/items/{publication_id}/history

Retrieve version history for a single publication with a specific id

HEADER
"Authorization" - authorization token
PARAMETER
-
CURL EXAMPLE
curl -X GET "https://dev.inge.mpdl.mpg.de/rest/items/item_123/history" -H "Authorization: {your_token_from_login}"


GET {base_url}/rest/items/{publication_id}/component/{file_id}/content

Retrieve a file content with a specific file id belonging to a specific publication id

HEADER
"Authorization" - authorization token
PARAMETER
-
CURL EXAMPLE
curl -X GET "https://dev.inge.mpdl.mpg.de/rest/items/item_123/component/file_123/content" -H "Authorization: {your_token_from_login}"


GET {base_url}/rest/items/{publication_id}/component/{file_id}/metadata

Retrieve a file content with a specific file id belonging to a specific publication id

HEADER
"Authorization" - authorization token
PARAMETER
-
CURL EXAMPLE
curl -X GET "https://dev.inge.mpdl.mpg.de/rest/items/item_123/component/file_123/metadata" -H "Authorization: {your_token_from_login}"


POST {base_url}/rest/items/search

Search for publications with the possibility to retrieve different formats and citations.
If you are calling the APIApplication Programming Interface to fill your homepage with larger amounts of publications, please read the scrolling section. If you are logged in then you can retrieve all your publications including pending and submitted publications. This can lead to duplicates because in our search engine the latest version and the latest released version is present.

HEADER
* "Content-Type" - application/json
"Authorization" - authorization token
PARAMETER
"format" - json (DEFAULT), eSciDocEnhanced Scientific Documentation_Itemlist_Xml, BibTexReference Management Software for Lists of References, Endnote, Marc_Xml, pdfPortable Document Format (citation expected), docx (citation expected), html_plain (citation expected), html_linked (citation expected), json_citation (citation expected), escidoc_snippet (citation expected)
"citation" - (for formats "(citation expected)" this parameter is required) - CSL (requires cslConeId), APAAmerican Psychological Association, APAAmerican Psychological Association(CJK), AJPApache JServ Protocol, JUS
"cslConeId" - if citation "CSL" is chosen, this parameter is required - z.B. http://pubman.mpdl.mpg.de/cone/citation-styles/resource/citation-styles186418
"scroll" - true/false - enables scrolling -> if enabled following scrolling results can be retrieved via {base_url}/rest/items/search/scroll
BODY
an Elasticserach query
{
    "query": {
        // filter all items within the context of the MPDLMax Planck Digital Library Publikations Context
        "term": {
            "context.objectId": {
                "value": "ctx_28054",
                "boost": 1.0
            }
        }
    },
    "sort": [
        {
            // define a sort criteria
            "metadata.title.keyword": {
                "order": "ASC"
            }
        }
    ],
    // limit the number of records which will be returned
    "size": "50",
    // define a start record (offset)
    "from": "0"
}
CURL EXAMPLE
curl -X POST "https://dev.inge.mpdl.mpg.de/rest/items/search?format=json_citation&citation=CSL&cslConeId=https://dev.inge.mpdl.mpg.de/cone/citation-styles/resource/citation-styles186418" 
-H "Authorization: {your_token_from_login}" -H 'Content-Type: application/json' -d 
'{
    "query": {
        "term": {
            "context.objectId": {
                "value": "ctx_28054",
                "boost": 1.0
            }
        }
    },
    "sort": [
        {
            "metadata.title.keyword": {
                "order": "ASC"
            }
        }
    ],
    "size": "50",
    "from": "0"
}'


SCROLLING
When doing requests with a high count of response publications, it is highly recommended to use scrolling. Scrolling will deliver the response in smaller packages (Default = 10 items) but you do not have to care about new entries, or the sorting, as you will get a saved response (server site) devided in smaller parts. You can define the number of items per package by using "size".


GET {base_url}/rest/items/search/scroll

Parameters are exaclty the same as for "POST {base_url}/rest/items/search" with the difference that you have no option to enable scrolling. Instead you can retrieve further scrolling results by adding the previous retrieved scrollId from a call to "POST {base_url}/rest/items/search".

HEADER
"Authorization" - authorization token
PARAMETER
"format" - json (DEFAULT), eSciDocEnhanced Scientific Documentation_Itemlist_Xml, BibTexReference Management Software for Lists of References, Endnote, Marc_Xml, pdfPortable Document Format (citation expected), docx (citation expected), html_plain (citation expected), html_linked (citation expected), json_citation (citation expected), escidoc_snippet (citation expected)
"citation" - (refer to formats "(citation expected)") CSL (requires cslConeId), APAAmerican Psychological Association, APAAmerican Psychological Association(CJK), AJPApache JServ Protocol, JUS
"cslConeId" - z.B. http://pubman.mpdl.mpg.de/cone/citation-styles/resource/citation-styles186418
"scrollId" - the scrollId you can retrieve via "POST {base_url}/rest/items/search", when you enable "scroll"
CURL EXAMPLE
curl -X GET "https://dev.inge.mpdl.mpg.de/rest/items/search?format=json_citation&citation=CSL&cslConeId=https://dev.inge.mpdl.mpg.de/cone/citation-styles/resource/citation-styles186418&scrollId=1A2B3C" 
-H "Authorization: {your_token_from_login}"