Skip to content

API documentation

Jump to bottom Edit New page
mariamoritz edited this page Nov 19, 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: "[email protected]",
   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" : "[email protected]", "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

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 will be reused. This 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 obj_get (/sentence/[id]/ on words)

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