API documentation

Non-Data Resources

Create user resource

post list

curl -X POST -H "Content-Type: application/json" --data '{"username" : "username", "email" : "[email protected]", "password" : "foo"}' --verbose http://localhost:8000/api/v1/create_user/?format=json | python -mjson.tool

User resource

login

curl -H "Content-Type: application/json" -X POST --data '{"username" : "foo", "password": "bar"}' --verbose http://localhost:8000/api/v1/user/login/?format=json | python -mjson.tool

logout

curl --cookie "sessionid=foo" -X GET http://localhost:8000/api/v1/user/logout/?format=json | python -mjson.tool

patch detail

curl -X PATCH -H "X-CSRFToken: foo" --cookie "sessionid=bar;csrftoken=foo" --data '{"first_name" : "john"}' http://localhost:8000/api/v1/user/3/?format=json | python -mjson.tool

Submission resource

list (after login)

curl -H "Content-Type: application/json" -X GET -H "X-CSRFToken: foo" --cookie "sessionid=bar;csrftoken=foo" --verbose http://localhost:8000/api/v1/submission/?format=json | python -mjson.tool

post list (after login)

curl -H "Content-Type: application/json" -X POST -H "X-CSRFToken: foo" --cookie "sessionid=bar;csrftoken=foo" -d '{"user":"john", "response": "responseString", "task": "taskString", "time": "50", "accuracy": "20", "encounteredWords": ["urn:cts:greekLit:tlg0003.tlg001.perseus-grc1:1.118.4:8","urn:cts:greekLit:tlg0003.tlg001.perseus-grc1:1.90.4:18"], "slideType": "treebank", "smyth": "s499", "timestamp": "2014-08-22T00:46:38"}' --verbose http://localhost:8000/api/v1/submission/?format=json | python -mjson.tool

Data Resources

Query the database individually for serving instances on list and detail views.

User Sentence Resource

list

http://localhost:8000/api/v1/user_sentence/?format=json

• contains all sentence properties
• words is null
• translations is null

detail

http://localhost:8000/api/v1/user_sentence/17799/?format=json

• contains all sentence properties
• contains all word properties of this sentence

full

http://localhost:8000/api/v1/user_sentence/17799/?format=json&full=True

• if full=True the translations of a word are also returned

post list (after login)

requires:document_resource_uri, CTS, word data & CTS of translated words

curl -H "Content-Type: application/json" -X POST -H "X-CSRFToken: foo" --cookie "sessionid=bar;csrftoken=foo" -d '

{
   "CTS": "urn:cts1",
   "document_resource_uri": "/api/v1/user_document/17788/",
   "words": [
       {
           "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:1",
           "lang": "fr",
           "tbwid": 1,
           "translations": ["urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:4"],
           "value": "les"
       },
       {
           "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:2",
           "lang": "fra",
           "tbwid": 2,
           "translations": ["urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:3"],
           "value": "word2"
       }
    ]
}

' --verbose http://localhost:8000/api/v1/user_sentence/?format=json | python -mjson.tool

returns: every submitted data

{
    "CTS": "urn:cts1", 
    "document_resource_uri": "/api/v1/user_document/17788/", 
    "words": [
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:1", 
            "lang": "fr", 
            "tbwid": 1, 
            "translations": [
                "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:4"
            ], 
            "value": "les"
        }, 
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:2", 
            "lang": "fra", 
            "tbwid": 2, 
            "translations": [
                "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:3"
            ], 
            "value": "word2"
        }
    ]
}

User Document Resource

###list http://localhost:8000/api/v1/user_document/?format=json

• contains all document properties
• contains resource uris to the sentences

detail

http://localhost:8000/api/v1/user_document/0/?format=json

• contains all document properties
• contains all sentence properties of this document's sentences

post list (after login)

curl -H "Content-Type: application/json" -X POST -H "X-CSRFToken: foo" --cookie "sessionid=bar;csrftoken=foo" -d '{"CTS": "urn:cts1", "author": "Thucydides", "lang": "fra", "name": "La Pent..."}' --verbose http://localhost:8000/api/v1/user_document/?format=json | python -mjson.tool

returns: every submitted data plus the resource uri

{
    "CTS": "urn:cts2",
    "author": "Thucydides",
    "lang": "fra",
    "name": "La Pent...",
    "resource_uri": "/api/v1/user_document/17788/"
}

Word Resource

###list http://localhost:8000/api/v1/word/?format=json&pos=verb&tense=pres&mood=ind&voice=act

• contains all word properties
• transaltions is null
• lemma-resource-uri is null

###detail http://localhost:8000/api/v1/word/445/?format=json

• contains all word properties
• contains a field with translation objects invluding resource-uri
• contains a lemma-resource-uri

smyth

http://localhost:8000/api/v1/word/smyth/?format=json&smyth=s217%23c !smyth key can also be queried for as a ordinary attribute filter on word list view!

• parameters: smyth=smythkey
• hint: # must be encoded %23 in the url
• returns a JSON object containing an array of hit words:

{
    "words": [
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc1:1.89.2:6",
            "case": "gen",
            "cid": 26870744,
            "dialect": "attic epic ionic",
            "form": "Εὐρώπης",
            "gender": "fem",
            "head": 4,
           ...
    ]
}

Sentence Resource

list

http://localhost:8000/api/v1/sentence/?format=json&CTS__contains=grc

• contains all sentence properties
• words is null

detail

http://localhost:8000/api/v1/sentence/27/?format=json

• contains all sentence properties
• contains all words of the sentence; words contain all word properties as well as the lemma-resource-uri

full

http://localhost:8000/api/v1/sentence/27/?format=json&full=True

• if full=True the translations of a word are also returned

short:

http://localhost:8000/api/v1/sentence/27/?format=json&short=True

• contains the sentence object with all sentence properties
• contains only the word objects after the shortening procedure

Document Resource

list

http://localhost:8000/api/v1/document/?format=json

• contains all document properties
• contains resource uris to the sentences

detail

http://localhost:8000/api/v1/document/0/?format=json

• contains all document properties
• contains all sentence properties of this document's sentences

Visualization Resource

encountered / word level

http://localhost:8000/api/v1/visualization/encountered/?format=json&level=word&range=urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.90.4:1-19&user=john

• parameters: level=word, user=username, range=wordCTS-lastWordNumber
• returns a JSON object containing a word array containing some information:

{
    "words": [
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.90.4:19",
            "morphKnown": true,
            "synKnown": false,
            "timesSeen": 1,
            "value": "λέγουσιν",
            "vocKnown": true
        },
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.90.4:20",
            "morphKnown": false,
            "synKnown": false,
            "timesSeen": 0,
            "value": "εὐθὺς",
            "vocKnown": false
        }
    ]
}

encountered / book level

http://localhost:8000/api/v1/visualization/encountered/?format=json&level=book&range=urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1&user=john

• parameters: level=book, user=username, range=documentCTS
• returns a JSON object containing a word array containing some information:

{
    "words": [
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.90.4:16",
            "morphKnown": false,
            "synKnown": false,
            "timesSeen": 2,
            "value": "πρέσβεις",
            "vocKnown": true
        },
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.90.4:17",
            "morphKnown": false,
            "synKnown": false,
            "timesSeen": 0,
            "value": "περὶ",
            "vocKnown": false

        },
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.90.4:18",
            "morphKnown": false,
            "synKnown": false,
            "timesSeen": 1,
            "value": "ὧν",
            "vocKnown": true
        }
    ]
}

encountered / document level

http://localhost:8000/api/v1/visualization/encountered/?format=json&level=document&range=urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1&user=john

• parameters: level=document, user=username, range=documentCTS
• returns a JSON object containing a sentence array containing some information:

{
    "sentences": [
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1",
            "lenth": 13,
            "one": 0.15384615384615385,
            "three": 0,
            "two": 0
        },
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.2",
            "lenth": 85,
            "one": 0,
            "three": 0,
            "two": 0
        },...
        {
            "CTS": "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.90.4",
            "lenth": 22,
            "one": 0.045454545454545456,
            "three": 0,
            "two": 0.045454545454545456
        }, ...
    ]
}

statistics

http://localhost:8000/api/v1/visualization/statistics/?format=json&range=urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1&user=john

• parameters: user=username, range=documentCTS
• returns a JSON object containing some information concerning the progress a user made related to a work:

{
    "statistics": {
        "all": 4643,
        "morphology": 0,
        "syntax": 0,
        "vocab": 0.0012922679302175318
    }
}

least accurate

http://localhost:8000/api/v1/visualization/least_accurate/?format=json&user=john

• parameters: user=username
• returns a JSON object containing a ranked array containing mainly the json smyth information to a user's submissions as well as the averaged accuracy (in percent) for this topic:

{
    "accuracy_ranking": [
        {
            "average": 15,
            "query": "pos=noun&posAdd=h_hs",
            "smyth": "s216",
            "title": "The Alpha or First Declension"
        },
        {
            "average": 20,
            "query": "pos=noun&gender=fem&lemma__endswith=α&posAdd__contains=h_hs",
            "smyth": "s217a",
            "title": "Feminine Nouns in the First Declension (α-stem)"
        },
        {
            "average": 20,
            "query": "pos=verb&tense=pres&mood=ind&voice=act&posAdd__contains=w_stem",
            "smyth": "s499",
            "title": "Form the Present, Active, Indicative for ω-stem Verbs"
        }
    ]
}

least recently

http://localhost:8000/api/v1/visualization/least_recently/?format=json&user=john

• parameters: user=username
• returns a JSON object containing a ranked array containing mainly the json smyth information to a user's submissions as well as the averaged time (Datetime string) since a user coped with this topic:

{
    "time_ranking": [
        {
            "average": "2014-02-20T13:46:38",
            "query": "pos=noun&gender=fem&lemma__endswith=α&posAdd__contains=h_hs",
            "smyth": "s217a",
            "title": "Feminine Nouns in the First Declension (α-stem)"
        },
        {
            "average": "2014-08-22T02:46:38",
            "query": "pos=noun&posAdd=h_hs",
            "smyth": "s216",
            "title": "The Alpha or First Declension"
        },
        {
            "average": "2014-08-22T02:46:38",
            "query": "pos=verb&tense=pres&mood=ind&voice=act&posAdd__contains=w_stem",
            "smyth": "s499",
            "title": "Form the Present, Active, Indicative for ω-stem Verbs"
        }
    ]
}