Implement a generic API to support custom exchanges

[jhamrick]

After discussions at the Edinburgh hackathon, I think it makes sense to at least implement a generic API for the exchange which would then support custom exchanges. While nbgrader itself will still use the same filesystem-based exchange (and wait for hubauth to be ready), this would enable others to experiment with alternate exchange implementations that work better for their setups.

@perllaghu @BertR you mentioned you have done something close to this already---would you be interested in porting what you have back to nbgrader? I am thinking it might make sense to have a plugin similar to the one added by #1093.

[perllaghu]

We really should..... for reference - here's our API docs [for our multi-course, pre-feedback, environment]. I post it to spark a discussion. (there are some issues that need to be addressed - not least of which is how some external exchange system authenticates users and gets any authoritative course and/or role for the user that can't be [easily] faked)

Assignments

.../assignments?course_id=$course_code

GET: returns list of assignments

Returns

    {"success": False, "note": $note}

or

{"success": True,
    "value": [{
        "assignment_id": $assignment_code,
        "course_id": $course_code,
        "status": Str,
        "path": path,
        "notebooks": [{"name": x.name} for x in assignment.notebooks],
        "timestamp": action.timestamp.strftime(
            "%Y-%m-%d %H:%M:%S.%f %Z"
        )},
        {},..
    ]}

(note that path may be the path to the object in the exchange [for released items] or on disk [for fetched items])

Assignment

.../assignment?course_id=$course_code&assignment_id=$assignment_code

GET: downloads assignment

Returns binary data or raises Exception

POST: (role=instructor, with file): Add ("release") an assignment returns

{"success": True, "note": "Released"}

or raises Exception

Submission

.../submission?course_id=$course_code&assignment_id=$assignment_code

POST: stores the submission for that user returns

{"success": True, "note": "Released"}

or raises Exception

Collections

.../collections?course_id=$course_code&assignment_id=$assignment_code

GET: gets a list of submitted items Return: same as Assignments

Collection

.../collections?course_id=$course_code&assignment_id=$assignment_code&path=$url_encoded_path

GET: downloads submitted assignment Return: same as Assignment

[jhamrick]

how some external exchange system authenticates users

Well, now that there's the Authenticator, I think it would make sense for the exchange code to query this to determine if a student has access before querying the external exchange service. Then you could implement and use complementary authentication plugins and exchange plugins.