Introduction
This section defines the expected structure of submissions to the API and describes normal interaction with the API using some examples of learners taking writing tests. The interaction is shown using the command line tool curl, but the requests could be made using any HTTP tool or library.
Structure of submissions
These are the assumptions that the API makes:
- text submitted to the API can come from many different learners (different
author_idvalues). - each learner can complete many different pieces of work (different
task_idvalues). - each learner can complete the same piece of work more than once (different
session_idvalues). - each piece of work can have a number of related questions (different
sequence_idvalues).
A piece of work defined by a task_id can have one or more questions (different sequence_id values). A piece of work can be an entire test, or a group of related questions that is part of a test. For example, a writing test might have 2 questions. The task_id would be the same for submission of answers to those questions.
The API will group submissions according to the author_id, task_id, session_id and sequence_id values.
For example, if a learner called "Learner1" completes a written test called "Task1" which has 2 questions, then the two answers will be individually submitted to the API with IDs:
- First answer:
author_id = "Learner1", task_id = "Task1", session_id = "Learner1Task1Session1", sequence_id = 1 - Second answer:
author_id = "Learner1", task_id = "Task1", session_id = "Learner1Task1Session1", sequence_id = 2
The author_id, task_id and session_id are the same because it is a single learner taking a test once. The sequence_id is different for each question in the same test.
If Learner1 completes the Task1 test a second time, then the session_id must change so the API can see that it was a different attempt of the test. For example:
- First answer:
author_id = "Learner1", task_id = "Task1", session_id = "Learner1Task1Session2", sequence_id = 1 - Second answer:
author_id = "Learner1", task_id = "Task1", session_id = "Learner1Task1Session2", sequence_id = 2
Then, a different learner called "Learner2" might complete the same task. The IDs used would then be:
- First answer:
author_id = "Learner2", task_id = "Task1", session_id = "Learner2Task1Session1", sequence_id = 1 - Second answer:
author_id = "Learner2", task_id = "Task1", session_id = "Learner2Task1Session1", sequence_id = 2
Here is a diagram illustrating this situation:
The author_id, task_id and session_id in these examples are very simple to help demonstrate what is expected. In reality, they are more likely to be less readable IDs. For example, UUIDs could be used so Learner1 could instead be 835bae38-a314-4969-b185-ebfc9563ac16, Task1 might be db4912c8-7032-42b8-8317-00e69bf5ca9d, Learner1's first attempt might have a session_id of 76ca3518-9cd3-4178-af01-786e234736c8 and their second attempt might have a session_id of 59f39503-b0d2-473c-9a61-391f6fa412c5. Learner2 could be 68a25500-df7d-4704-8547-720fd80ee2fe and their session_id could be 377d6e77-4e82-4745-8101-1edfdf0abb36.
Of course, the question and answer text and other parameters are also required in each case. The following sections provide full examples.
Text submission and results retrieval
The examples in this section show submission and results retrieval for two learners called "Learner1" and "Learner2". Learner1 completes a written test called "WritingTask1" which has 2 questions and later tries the same test again. Learner2 completes the "WritingTask1" test once and later tries another test called "WritingTask2" which also has 2 questions.
Learner1 WritingTask1 first attempt
Learner1 has completed WritingTask1 and now it must be assessed. First, submit the answers for the 2 questions in WritingTask1:
Answer for question 1 (sequence_id 1)
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner1",
"task_id": "WritingTask1",
"session_id": "Learner1WritingTask1Session1",
"sequence_id": 1,
"sequence_count": 2,
"question_text": "Describe a famous person from your country",
"text": "There are many famos people from my country. Where to begin? Im not shure."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s1a1
# response
# {
# "type": "success",
# "code": 200
# }
Answer for question 2 (sequence_id 2):
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner1",
"task_id": "WritingTask1",
"session_id": "Learner1WritingTask1Session1",
"sequence_id": 2,
"sequence_count": 2,
"question_text": "Who is your favourite superhero and why?",
"text": "I dont know. It is difficult to choose because there are many I like. Perhaps supermann."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s1a2
# response
# {
# "type": "success",
# "code": 200
# }
You can see that the author_id, task_id and session_id are the same. This enables the API to see that the two submissions are related. They are both written by the same learner (author_id: Learner1), for a single attempt (session_id: Learner1WritingTask1Session1) at the same test (task_id: WritingTask1).
Now the results can be retrieved.
Results for answer to question 1:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s1a1/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": :3.63727,
# "sentence_scores": [
# [0, 44, -1],
# [46, 61, 0.467791],
# [62, 75, -1]
# ],
# "suspect_tokens": [],
# "textual_errors": [
# [15, 20, "famous", "S"],
# [62, 64, "I'm", "MP"],
# [69, 74, "sure", "S"]
# ]
# }
Results for answer to question 2:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s1a2/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": 3.63727,
# "sentence_scores": [
# [0, 12, -0.825816],
# [14, 70, -0.34672],
# [72, 90, 0.354242]
# ],
# "suspect_tokens": [
# [2, 6]
# ],
# "textual_errors": [
# [2, 6, "don't", "MP"],
# [48, 53, "there", "SX"]
# ]
# }
Now you have submitted Learner1's first attempt at the WritingTask1 test and successfully retrieved the results.
Learner1 WritingTask1 second attempt
Next, Learner1 tries the WritingTask1 test again, so this must be assessed by the API.
First, you submit the answers for the 2 questions in WritingTask1. Notice that the session_id is different from the answers submitted for their first attempt:
Answer for question 1 (sequence_id 1)
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner1",
"task_id": "WritingTask1",
"session_id": "Learner1WritingTask1Session2",
"sequence_id": 1,
"sequence_count": 2,
"question_text": "Can you tell us about some famous people from your country?",
"text": "There are many famos people from my country. Where to begin? Im still not shure."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s2a1
# response
# {
# "type": "success",
# "code": 200
# }
The author_id and task_id are the same as before, because it is the same learner and task. The session_id has changed because this is the second time they have taken the test.
Answer for question 2 (sequence_id 2):
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner1",
"task_id": "WritingTask1",
"session_id": "Learner1WritingTask1Session2",
"sequence_id": 2,
"sequence_count": 2,
"question_text": "Who is your favourite superhero and why?",
"text": "I dont know. Maybe Batman is the best because he has a grate car!"
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s1a2
# response
# {
# "type": "success",
# "code": 200
# }
You can see that the author_id, task_id and session_id are the same as for Learner1's first answer of their second attempt at Task1 (the previous answer submitted with ID l1t1s2a1). This enables the API to see that the two submissions are related. They are both written by the same learner (author_id: Learner1), for the second attempt (session_id: Learner1WritingTask1Session2) of the same test (task_id: WritingTask1).
Now the results can be retrieved.
Results for answer to question 1:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s2a1/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": 3.70231,
# "sentence_scores": [
# [0, 44, -1.0],
# [46, 61, 0.467791],
# [62, 81, -1.0]],
# "suspect_tokens": [
# [15, 20],
# [62, 64],
# [65, 70],
# [75,80]
# ],
# "textual_errors": [
# [15, 20, "famous", "S"],
# [62, 64, "I'm", "MP"],
# [75, 80, "sure", "S"]
# ]
# }
Results for answer to question 2:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l1t1s2a2/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": 3.70231,
# "sentence_scores": [
# [0, 12, -0.825816],
# [14, 66, -0.662313]
# ],
# "suspect_tokens": [
# [2, 6],
# [56, 61]
# ],
# "textual_errors": [
# [2, 6, "don't", "MP"],
# [56, 61, "great", "SX"]
# ]
# }
Learner2 Task1 single attempt
Learner2 then tries WritingTask1, so the data is then submitted for assessment.
Answer for question 1 (sequence_id 1)
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner2",
"task_id": "WritingTask1",
"session_id": "Learner2WritingTask1Session1",
"sequence_id": 1,
"sequence_count": 2,
"question_text": "Describe a famous person from your country",
"text": "The prime minister of my country is very famous. He has done meny good things for our country and other countrys."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t1s1a1
# response
# {
# "type": "success",
# "code": 200
# }
Answer for question 2 (sequence_id 2):
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner2",
"task_id": "WritingTask1",
"session_id": "Learner2WritingTask1Session1",
"sequence_id": 2,
"sequence_count": 2,
"question_text": "Who is your favourite superhero and why?",
"text": "I like spider man. It is realy cool that he can swing between the tall buildings."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t1s1a2
# response
# {
# "type": "success",
# "code": 200
# }
You can see that the author_id, task_id and session_id for these two submissions are the same. This enables the API to see that the two submissions are related. They are both written by the same learner (author_id: Learner2), for a single attempt (session_id: Learner2WritingTask1Session1) of the same test (task_id: WritingTask1).
Now the results can be retrieved.
Results for answer to question 1:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t1s1a1/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": 3.99879,
# "sentence_scores": [
# [0, 48, 0.859568],
# [50, 114, -1.0]
# ],
# "suspect_tokens": [
# [57, 61],
# [62, 66],
# [105,113]
# ],
# "textual_errors": [
# [62, 66, "many", "S"],
# [105, 113, "countries", "IN"]
# ]
# }
Results for answer to question 2:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t1s1a2/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": 3.99879,
# "sentence_scores": [
# [0, 18, -0.209531],
# [20, 82, -0.668889]
# ],
# "suspect_tokens": [
# [26, 31]
# ],
# "textual_errors": [
# [26, 31, "really", "DY"]
# ]
# }
Learner2 Task2 single attempt
Learner2 then tries a different task: WritingTask2.
First the two answers are submitted:
Answer for question 1 (sequence_id 1)
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner2",
"task_id": "WritingTask2",
"session_id": "Learner2WritingTask2Session1",
"sequence_id": 1,
"sequence_count": 2,
"question_text": "What things are there for tourists to do in your town?",
"text": "There are many interesting things to do in my town. You can visit the old castle if you wish. You can also go to cinema."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t2s1a1
# response
# {
# "type": "success",
# "code": 200
# }
Answer for question 2 (sequence_id 2):
$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
"author_id": "Learner2",
"task_id": "WritingTask2",
"session_id": "Learner2WritingTask2Session1",
"sequence_id": 2,
"sequence_count": 2,
"question_text": "What do you like best about the country you live in?",
"text": "I like the varied scenery. There are mountains, plains and the seeside."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t2s1a2
# response
# {
# "type": "success",
# "code": 200
# }
You can see that the author_id, task_id and session_id are the same. This enables the API to see that the two submissions are related. They are both written by the same learner (author_id: Learner2), for a single attempt (session_id: Learner2WritingTask2Session1) at the same test (task_id: WritingTask2).
Now the results can be retrieved.
Results for answer to question 1:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t2s1a1/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": 4.06784,
# "sentence_scores": [
# [0, 51, 1.0],
# [53, 94, 0.532845],
# [96, 122, -1.0]
# ],
# "suspect_tokens": [],
# "textual_errors":[
# [112, 114, "the", "+MD"],
# [115, 121, "the", "MD+"]
# ]
# }
Results for answer to question 2:
curl -H "Authorization: Token token=YOUR_TOKEN" https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/l2t2s1a2/results
At first, the API may still be assessing the answer, so you may receive the following response:
# response
# {
# "type": "results_not_ready",
# "code": 200
# }
You can try the request again after 30 seconds and if the API has finished assessing the answer, you should receive a response like this:
# {
# "type": "success",
# "code": 200,
# "overall_score": 4.06784,
# "sentence_scores": [
# [0, 26, 0.415184],
# [28, 72, -0.55724]
# ],
# "suspect_tokens": [
# [64, 71]
# ],
# "textual_errors": [
# [64, 71, "seaside", "S"]
# ]
# }