Carnap API

Carnap has an experimental API, which is currently under development (see the tracking issues below).

Tracking issues

Instructor setup

You can add an API key on the instructor page on the "Manage Uploaded Documents" page here:

image showing the API key field at the bottom of the screen

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

apikey = 'REDACTED'

base = 'http://localhost:3000/api/v1'

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).

Tracking issue

GET /instructors/:instructorIdent/documents

Retrieves a list of documents owned by the given instructor and their metadata. Here are some example commands:

Python

rq('GET', '/instructors/yourname@gmail.com/documents').json()

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

rq('POST', '/instructors/yourname@gmail.com/documents',
    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

rq('GET', '/instructors/yourname@gmail.com/documents/1').json()

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

rq('PATCH', '/instructors/yourname@gmail.com/documents/1',
    json={"scope": "Private"}).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

rq('GET', 'instructors/yourname@youremail.com/documents/1/data').text

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

rq('PUT', '/instructors/yourname@gmail.com/documents/1/data', data='aaaaaa')

Bash

echo aaaaaa | curl -H "X-API-KEY:YOURAPIKEYHERE"  -T "-" \
    localhost:3000/api/v1/instructors/gleachkr@gmail.com/documents/1940/data

Result

<Response [200]>