Self-Test: API

Self-Test: API#

Note

This self-test supports Chapter 5 (API: Working with DraCor Programmatically). It checks key concepts and basic hands-on skills.

  • There is no grading and nothing is stored.

  • Multiple-choice questions provide feedback for every option.

  • Coding tasks are presented as (a) a student prompt, (b) a reference solution shown as code, and (c) an executed reference output.

Estimated time: 25–40 minutes.

Question 1#

Question 2#

Question 3#

Question 4#

Question 5#

Question 6#

Question 7#

Student exercise (copy into a notebook, fill in, run):

import requests

url = "https://dracor.org/api/v1/corpora"
params = {"include": "metrics"}

# TODO: send request with a timeout
# TODO: check status code
# TODO: parse JSON to a Python list
# TODO: print the number of corpora
# TODO: print the first 5 corpus identifiers and titles: "<name>: <title>"

Self-check:

  • You should see an integer number of corpora.

  • You should see 5 lines like ger: German Drama Corpus (exact titles vary).

Reference solution (code)

import requests

url = "https://dracor.org/api/v1/corpora"
params = {"include": "metrics"}

r = requests.get(url, params=params, timeout=30)
if r.status_code != 200:
    print(f"Request failed with status code: {r.status_code}")
else:
    corpora = r.json()
    print(f"Number of corpora: {len(corpora)}")
    for c in corpora[:5]:
        print(f"{c.get('name')}: {c.get('title')}")

Executed reference output:

Number of corpora: 24
als: Alsatian Drama Corpus
am: American Drama Corpus
ar: Argentinian Drama Corpus
bash: Bashkir Drama Corpus
cal: Calderón Drama Corpus

Question 8#

Student exercise (copy into a notebook, fill in, run):

import requests

API_URL = "https://dracor.org/api/v1/"
corpusname = "ger"
playname = "lessing-emilia-galotti"
url = f"{API_URL}corpora/{corpusname}/plays/{playname}"

# TODO: send a GET request with a timeout
# TODO: if status 200, parse the JSON response
# TODO: print:
#   - the play title
#   - the normalised year
#   - the number of speakers
#   - the average degree (if available)
# TODO: otherwise, print "Request failed with status code: <status>"

Self-check:

  • You should see basic play metadata for Emilia Galotti.

  • The output should contain the title, a year, and at least one network-related value.

Reference solution (code)

import requests

API_URL = "https://dracor.org/api/v1/"
corpusname = "ger"
playname = "lessing-emilia-galotti"
url = f"{API_URL}corpora/{corpusname}/plays/{playname}"

r = requests.get(url, timeout=15)

if r.status_code != 200:
    print(f"Request failed with status code: {r.status_code}")
else:
    data = r.json()
    print(f"Title: {data.get('title')}")
    print(f"Year: {data.get('yearNormalized')}")
    print(f"Speakers: {data.get('numOfSpeakers')}")
    print(f"Average degree: {data.get('averageDegree')}")

Executed reference output:

Title: Emilia Galotti
Year: 1772
Speakers: None
Average degree: None

Question 9#

Student exercise (copy into a notebook, run). The endpoint is intentionally wrong so that you can practise interpreting an error response:

import requests

url = "https://dracor.org/api/v1/corpora/rus/plays/lessing-emilia-galotti"
r = requests.get(url, timeout=15)

# TODO: if status 200, print the play title from JSON
# TODO: otherwise, print "Request failed with status code: <status>"

Self-check:

  • You should get a non-200 status code, typically 404.

  • This shows that a play slug only works inside the correct corpus.

Reference solution (code)

import requests

url = "https://dracor.org/api/v1/corpora/rus/plays/lessing-emilia-galotti"
r = requests.get(url, timeout=15)

if r.status_code == 200:
    data = r.json()
    print(f"Play title: {data.get('title')}")
else:
    print(f"Request failed with status code: {r.status_code}")

Executed reference output:

Request failed with status code: 404

Question 10#

Student exercise (copy into a notebook, fill in, run):

import requests

corpusname = "ger"
playname = "lessing-emilia-galotti"
url = f"https://dracor.org/api/v1/corpora/{corpusname}/plays/{playname}/characters"

# TODO: request CSV using the Accept: text/csv header
# TODO: print the first 5 non-empty lines of the response

Self-check:

  • You should see a header row (CSV column names), then character rows.

Reference solution (code)

import requests

corpusname = "ger"
playname = "lessing-emilia-galotti"
url = f"https://dracor.org/api/v1/corpora/{corpusname}/plays/{playname}/characters"

r = requests.get(url, headers={"Accept": "text/csv"}, timeout=15)

if r.status_code != 200:
    print(f"Request failed with status code: {r.status_code}")
else:
    lines = [ln for ln in r.text.splitlines() if ln.strip()]
    for ln in lines[:5]:
        print(ln)

Executed reference output:

id,name,sex,isGroup,numOfScenes,numOfSpeechActs,numOfWords,wikidataId,degree,weightedDegree,betweenness,closeness,eigenvector
"der_prinz","Der Prinz","MALE","false","17","157","4002",,"8","20","0.46717171717171724","0.75","0.32076106311648156"
"der_kammerdiener","Der Kammerdiener","MALE","false","2","6","33",,"1","2","0","0.4444444444444444","0.05575792046031641"
"conti","Conti","MALE","false","2","24","604",,"1","2","0","0.4444444444444444","0.05575792046031641"
"marinelli","Marinelli","MALE","false","19","221","4343",,"9","30","0.24696969696969698","0.8","0.4489846359321899"