Skip to content

API documentation

Jump to bottom Edit New page
mariamoritz edited this page Dec 15, 2014 · 68 revisions

Intro

All API urls here are prefixed by /api/v1/. So, for example, if you see an entry that says "POST /create_user/", it is referring to sending a POST request to /api/v1/create_user/.

You can explore all the available endpoints by checking out: /api/v1/?format=json.

Each API Resource is in its own file (with the exception of Contributions, described later) in the api/ folder. Generally, the file name also maps to the url endpoint.

All of the API urls are registered with the project in /phaidra/urls.py.

User-related Resources

{
   email: "lent.monica@gmail.com",
   first_name: "Monica",
   id: 1,
   is_superuser: true,
   lang_learning: {
       direction: "ltr",
       id: 5,
       local_name: "Ἑλληνική",
       locale: "greek",
       modern: false,
       name: "Ancient Greek",
       resource_uri: "/api/v1/language/5/",
       short_code: "grc"
   },
   lang_speaking: {
      direction: "ltr",
      id: 4,
      local_name: "English",
      locale: "en-US",
      modern: true,
      name: "English",
      resource_uri: "/api/v1/language/4/",
      short_code: "en"
   },
   last_name: "Lent",
   resource_uri: "/api/v1/user/1/",
   username: "monica"
}

Create User Resource

POST /create_user/

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

User Resource: /user/

POST /user/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

GET /user/logout/

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

GET /user/

Retrieves only the user who is logged in.

PATCH /user/[id]

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

The values available at /submission/ are automatically filtered by the logged in user's id.

/submission/ (must be authenticated)

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 /submission/ (must be authenticated)

{
   "response": "beta",
   "task": "identify_letter:beta",
   "accuracy": 100,
   "encounteredWords": ["urn:cts:greekLit:tlg0003.tlg001.perseus-grc1:1.118.4:8"],
   "ref": "s1",
   "timestamp": "2014-08-22T00:46:38",
   "starttime": "2014-08-22T00:45:38"
}

curl -H "Content-Type: application/json" -X POST -H "X-CSRFToken: foo" --cookie "sessionid=bar;csrftoken=foo" -d '{"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"], "smyth": "s499", "timestamp": "2014-08-22T00:46:38", "starttime": "2014-08-22T00:45:38"}' --verbose http://localhost:8000/api/v1/submission/?format=json | python -mjson.tool

  • On submission, the API checks if the current user already has submissions, if not a neo node with the users name is created. The session is created as a node and the relation between both is set.
  • On submission, the smyth ref is used to filter (No MULTI VALUES supported for this filter) the word list, all words hitting the smyth ref receive a relation knows_morph from the user to the word node, if not already there.
  • On submission, the encoundereWords list is scanned and a relation has_seen is set between the user and the word node and the user and the lemma node of the word; if the user vs. word relation already existed, a relationship attribute times_seen is incremented else.

Textual API Endpoints

Caching

Caches are configured in Word, Lemma and Document resources as:

cache = SimpleCache(timeout=None)

Sentence caching is implemented inline, because several parameters (default, full, short, full_short) create several caching objects.

Sorting

Cypher queries return words within a sentence and sentences within a document ordered by ID. When a database is built and indices are assigned to the node ID, IDs of formerly deleted nodes (like during a test phase of development) will be reused. This is why sorting functions are implemented in (api/utils.py) and used in the following resource functions:

document get_object_list (/document/ on sentences)
document obj_get (/document/[id]/ on sentences)
sentence get_object_list (/sentence/ on sentences)
sentence obj_get (/sentence/[id]/ on words)

Out of calculation complexity reasons, config parameters were introduced in phaidra/phaidra/settings.py To allow sorting on:

word get_object_list (/word/any_filter on words)

the parameter is set to True. Switch it to False:

ENABLE_WORD_LIST_SORTING = False

to disable sorting and receive more than the first 500 words of a query.

Another parameter disables the sentence sortening of documents containing more than 500 sentences. If this is switched to False, a long document might not be displayed due to the recursion depth limit (See the neo4j docu and the Django docu to adapt stack sizes). If set to True (default), no sorting happens on documents longer than 500 sentences. Set it to False like:

ENABLE_DISPLAYING_LONG_DOCUMENTS = False

It is therefore higly recommended to not delete nodes on a production system OR to built a fresh database on a production system after testing (deleting recreating) nodes.

Word Resource: /word/

{
    meta: {
        limit: 20,
        next: "/api/v1/word/?lang=grc&offset=20&limit=20&format=json",
        offset: 0,
        previous: null,
        total_count: 4643
    },
    objects: [
        {
            CTS: "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1:1",
            case: "nom",
            cid: 26870726,
            degree: null,
            dialect: "",
            form: "οἱ",
            gender: "masc",
            head: 3,
            isIndecl: "proclitic indeclform",
            lang: "grc",
            lemma: "ὁ",
            lemma_resource_uri: null,
            length: 2,
            mood: null,
            number: "pl",
            person: null,
            pos: "article",
            posAdd: null,
            posClass: "N",
            ref: "1.089.1-001",
            relation: "ATR",
            resource_uri: "/api/v1/word/2/",
            sentence_resource_uri: "/api/v1/sentence/1/",
            tbwid: 1,
            tense: null,
            translations: null,
            value: "οἱ",
            voice: null
        }
    ]
}

GET /word/

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

  • Takes Ref keys and all word properties as filters ref=refkey (# has to be escaped by %23)
  • Requires: if no other filters are submitted - at least the document CTS, otherwise an empty list is returned, because object list method needs to return an object list or empty list (see Validation)!
  • Contains all word properties
  • transaltions is null
  • lemma_resource_uri is null

GET /word/[id]/

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

  • Contains all word properties
  • Contains a field with translation objects including resource_uri
  • Contains a lemma_resource_uri

fuzzy filtering

http://localhost:8000/api/v1/word/?format=json&lemma__contains=γκ&posAdd__endswith=hs

  • Fuzzy filters are implemented. Such as: contains, startswith, endswith and isnot (and lt, gt for numeric values).

multiple value support

http://localhost:8000/api/v1/word/?format=json&lemma__contains=γκ\_\_γγ\_\_γξ&pos=noun\_\_verb

  • Multiple value support is enabled for all filters. Simply put a double underscore inbetween your values.

Tastypie does not support parameters like (unhashable type exception): /api/v1/word/?lemma__contains=["γκ","γγ","γξ"] Tastypie does not support multiple parameters like the following, for non orm data sources, because request parameters are treated as a dictionary: /api/v1/message/?lemma__contains=γκ&lemma__contains=γγ&lemma__contains=γξ A filter implementation might be necessary, but filtering after creating the whole object list is maybe not preferred.

Sentence Resource: /sentence/

{
    meta: {
        limit: 20,
        next: "/api/v1/sentence/?offset=20&limit=20&format=json",
        offset: 0,
        previous: null,
        total_count: 178
    },
    objects: [
        {
            CTS: "urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1",
            document_resource_uri: "/api/v1/document/0/",
            length: 13,
            resource_uri: "/api/v1/sentence/1/",
            sentence: "οἱ γὰρ Ἀθηναῖοι τρόπῳ τοιῷδε ἦλθον ἐπὶ τὰ πράγματα ἐν οἷς ηὐξήθησαν . ",
            translations: null,
            words: null
        }
    ]
}

GET /sentence/

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

  • Contains all sentence properties
  • words is null

GET /sentence/[id]/

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 lemma_resource_uri

GET /sentence/[id]/?full=True

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

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

GET /sentence/[id]/?short=True:

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

fuzzy filtering

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

  • Fuzzy filters are implemented. Such as: contains, startswith, endswith and isnot (lt, gt for numeric values).

Document Resource: /document/

GET /document/

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

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

GET /document/[id]/

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

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

fuzzy filtering

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

  • Fuzzy filters are implemented. Such as: contains, startswith, endswith and isnot.

Visualization Resource

GET /visualization/encountered/?level=word

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 Accepted: 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
        }
    ]
}

GET /visualization/encountered/?level=book

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

  • Parameters Required: 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
        }
    ]
}

GET /visualization/encountered/?level=document

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
        }, ...
    ]
}

GET /statistics/

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

  • Parameters Required: 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
    }
}

GET /visualization/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"
        }
    ]
}

GET /visualization/least_recently/

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

  • Paramters: 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 worked on 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"
        }
    ]
}

User Contribution Resources

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

Validation

Is done on all data resources' and user data resources' list views, because there paramaters for filtering and querying are submitted. Validation is checked within the obj_get_list method, which for example branches authorized list reading in the submission resource. Returned is a list of errors, but since tastypie requires any kind of object list (also an empty list) as return parameter, it just throws a general internal server error (e.g. Because the error hasn't a certain attribute).

User Sentence Resource

translations

http://localhost:8000/api/v1/user_sentence/translations/?format=json&CTS=urn:cts:greekLit:tlg0003.tlg001.perseus-grc:1.89.1

  • parameters: CTS=CTS_of_the_greek_sentence
  • returns a list of sentences containing all sentence properties
  • words is null
  • translations is null

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/"
}
Add a custom footer

Developer Guide

Backend

Frontend

Content Guide

What did you break?

  • Postgres Database
  • Neo4j
  • Django
  • "The server"
  • Git
  • UI
Clone this wiki locally