Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Markus API Design #1002
Rough documentation for the API can be found at: https://github.com/MarkUsProject/Markus/wiki/ApiHowTo
Because the api uses the show action, the path for getting a submission download must have an :id. This value isn't used or checked in the method's code, but is simply necessary as the default routes requires it. As a result, it would be more suitably written with the index action.
So, to download a submission, the url will look like the following:
In other APIs, the 1 that sometimes precedes the request signifies the API version, but in our case it is clearly used by rails and mapped as the value for the parameter "id".
Testing that API call, I use the following:
(note: quotes are required to handle the ampersands, and -O to download the zip rather than print its contents)
Which successfully downloads the file:
Once again, because we're using "show", but the :id is not provided, we must pass an arbitrary id to get details on a single user:
If the API used the :id, the request URL would instead be:
To upload a new test result for a submission, you can use a request such as the following:
If the test framework isn't enabled, rather than get a simple error message, we get a page long trace, including this:
Otherwise, upon success, it'll output:
Getting a test result, on the other hand, can be done with the following:
Testing of main_api_controller, test_results_controller, and users_controller are all very exhaustive. However, no test cases exist for submission_downloads_controller.
Referring to the standard methods outlined at:
These correspond to the following default Rails "resources" controller actions: index, show, update, new, and destroy. These methods are the same as what is already available, but their use, in terms of collections/subcollections, and identification of individual resources is what would change. Nested routes would allow us to capture the relationsip between the different collections/resources/sub-collections: http://guides.rubyonrails.org/routing.html#nested-resources. For example, using a recommended maximum 1 level deep of nested routes: /api/collection/resource/sub-collection/resource
This would be written as I continue to work on it...
Note that in the above, I used a 2-level nested route for the test_results, despite it often being recommended to limit it to 1 level as seen with the rest of our routes. However, I feel as though it would be the most appropriate as it shows the logical relationship between assignments/submissions/test_results, and the alternative would be to have test_results as a top level collection.
Input on that, and anything else in this proposal/issue would be great! Thanks :)
This sounds good to me. @etraikov worked on a new api design for assignments quite a while back, which never got merged. It's one of these reviews:
Reviewboard on markusproject is offline though. We'd need @benjaminvialle to resurrect these (if that's possible at all). Anyhow so far my info. Cheers!
For some of reviews still up-to-date on ReviewBoard, I created Github issues with gist associated:
#745 (and https://gist.github.com/4055130)
If it is not enough, I can start again reviewboard. Let me know :)
4055313 contains code relating to assignments, and I'll definitely look at parts of the implementation.
As for 4055194, I haven't tested it, but it seems to me that it would give students full access to the admin API. I'm pretty sure this is currently the only thing stopping it:
Are we interested in allowing students to use parts of the API as well? I'm not sure what would be helpful, as they shouldn't be performing nearly as many bulk tasks.
@benjaminvialle @jerboaa What would either of you think of removing the plaintext responses from the API? That is, only offerring XML and JSON responses. The reason I ask is because some of the language keys in the yml files have HTML syntax, ie:
So if I try to print short_identifier or due_date, the plaintext response will have the above span elements. To avoid that, we'd either have to modify the corresponding views and place the span in there, or duplicate a lot of existing languages keys, which also isn't a good solution. I'd appreciate some input on this.
referenced this issue
Apr 1, 2013
@benjaminvialle Progress on documentation can be found here: https://github.com/danielstjules/Wiki/blob/issue-1002/RESTfulApiDocumentation.rst I'd appreciate any constructive criticism :)
Also, I'll be working on Test Results next. Just going to go back and forth between that and the documentation.