Carnap API
Carnap has an experimental API, which is currently under development (see the tracking issues below).
Tracking issues
- Issue #226 "Perform instructor actions via an API"
- Issue #231 "Documents API"
- Issue #230 "Copy course"
Instructor setup
You can add an API key on the instructor page on the "Manage Uploaded Documents" page here:
Usage
Example Scripts
Here are some examples for how you can get into a position to start using the
API with different programming languages. We assume that you're testing, so the
URL begins with http://localhost:3000
, but this should of course be
https://YOURSERVERRDOMAIN
when you're using this with a non-local server
Python
Create the file apitest.py
:
import requests
= 'REDACTED'
apikey
= 'http://localhost:3000/api/v1'
base
def rq(meth, p, *args, key=apikey, **kwargs):
= {
h 'X-API-KEY': key,
}return requests.request(meth, base + p, *args, **kwargs, headers=h)
To issue the commands displayed below interactively ipython -i apitest.py
, or
python -i apitest.py
.
Bash
Just use curl
as indicated below.
Methods
Document API
All of the methods in the documents API require that :instructorIdent
is
the same as the user who owns the API key (i.e. they do not work on other
users' documents yet).
GET /instructors/:instructorIdent/documents
Retrieves a list of documents owned by the given instructor and their metadata. Here are some example commands:
Python
'GET', '/instructors/yourname@gmail.com/documents').json() rq(
Bash
curl -H "X-API-KEY:YOURAPIKEYHERE" localhost:3000/api/v1/instructors/yourname@youremail.com/documents
Result
And here's what your result will look like:
'creator': 1,
[{'date': '2021-02-16T09:41:39.445672522Z',
'scope': 'Public',
'id': 1,
'description': None,
'filename': 'api.md'}]
POST /instructors/:instructorIdent/documents
Creates a new document with empty contents. Should be followed by a PUT
at
/instructors/:instructorIdent/documents/:documentId/data
in order to fill in
the document contents.
Python
'POST', '/instructors/yourname@gmail.com/documents',
rq(={
json"filename": "myfile.md",
"scope": "Private",
"description": "My file",
} ).json()
Bash
curl -H "X-API-KEY:YOURAPIKEY" \
-H "Content-Type: application/json" \
-d '{"filename":"myfile.md","scope":"Private", "description":"My file"}' \
localhost:3000/api/v1/instructors/yourname@gmail.com/documents
Result
3
or an error is returned as an encoded JSON string.
The response will also include a Location
header pointed at the new resource.
scope
indicates the sharing scope of the document, and can be one of
Private
, Public
, LinkOnly
or InstructorsOnly
. Both the scope and
description fields can be omitted, with scope defaulting to Private
.
GET /instructors/:instructorIdent/documents/:documentId
Like GET /instructors/:instructorIdent/documents
but for a single document.
Python
'GET', '/instructors/yourname@gmail.com/documents/1').json() rq(
Bash
curl -H "X-API-KEY:YOURAPIKEYHERE" localhost:3000/api/v1/instructors/yourname@youremail.com/documents/1
Result
'creator': 1,
{'date': '2021-02-16T09:41:39.445672522Z',
'scope': 'Public',
'description': None,
'filename': 'api.md'}
PATCH /instructors/:instructorIdent/documents/:documentId
Updates the metadata for a single document
Python
'PATCH', '/instructors/yourname@gmail.com/documents/1',
rq(={"scope": "Private"}).json() json
Bash
curl -H "X-API-KEY:YOURAPIKEY" -X "PATCH" -d '{"scope":"Public"}' \
localhost:3000/api/v1/instructors/yourname@youremail.com/documents/1
Result
'creator': 1,
{'date': '2021-02-16T09:41:39.445672522Z',
'scope': 'Private',
'description': None,
'filename': 'api.md'}
Currently scope
and description
fields can be updated. Passing in a null
value for description
will cause the document description to be cleared
entirely.
GET /instructors/:instructorIdent/documents/:documentId/data
Gets the content of the given document by ID and returns it.
Python
'GET', 'instructors/yourname@youremail.com/documents/1/data').text rq(
Bash
curl -H "X-API-KEY:YOURAPIKEYHERE" \
localhost:3000/api/v1/instructors/yourname@youremail.com/documents/1/data
Result
The contents of your document, as text
PUT /instructors/:instructorIdent/documents/:documentId/data
Overwrites the content of the given document by ID. These examples us "aaaaaa" as a thing you might insert as the document contents.
Python
'PUT', '/instructors/yourname@gmail.com/documents/1/data', data='aaaaaa') rq(
Bash
| curl -H "X-API-KEY:YOURAPIKEYHERE" -T "-" \
echo aaaaaa 3000/api/v1/instructors/gleachkr@gmail.com/documents/1940/data localhost:
Result
<Response [200]>