Web API Access for The Gadfly Project by the Vandals

A webservice to access The Gadfly Project.

1. Clone the repo
2. (optionally) Create Virtual Env
3. Install Python requirements pip install -r requirements.txt

Review the section on Feature Branch Workflow to get an overview of how to contribute to this project.

Clone the repo.
git clone <repo url>

Create a new branch for the feature that you are working on. You should not be developing on the master branch. "Feature branches should have descriptive names, like animated-menu-items or issue-#1061. The idea is to give a clear, highly-focused purpose to each branch."
git checkout -b <feature_name>

Focus on committing your code often to the branch. Each commit should have a useful commit message that explains what has been commited.
git add <all_files_to_include_in_commit>
git commit -m "<useful_commit_message>

When you feel like you have completed working on your feature, review the commits on your branch.
git log --oneline

During this step, you may recognize that several commits can/should be collapsed into one commit. You can/should edit your git commit history by using the following command. Read the following link on git rebase -i. Combine/split your commits into an easy to follow history.
git rebase -i

Push your branch to remote.
git push origin <branch_name>

Submit a pull request by navigating to the project Github page and submitting a pull request (More Instructions Here). Give your project teammates a few days to review your pull requests and address any questions or feedback that they have on your code and submit additional pull requests as necessary. Once your pull request has been accepted, you may merge to master and push to origin.

The Gadfly Web API consists of HTTP RPC-style methods, all of the form [hostname]/api/METHOD. Arguments can be passed as GET or POST params, or a mix. The response contains a JSON object.

Use this method to retrieve a set of gap fill questions. This method has the URL [hostname]/api/gap_fill_questions. Pass the news article URL to this as an argument. You can also limit the number of question objects in the response by using the limit parameter.

Response

{  
  'num_questions': number of questions that were generated from the url you passed,  
  'questions': the questions object which contains individual question items  
}  

The Question object contains

an id unique to the question item [id]  
the question text [question_text]  
the source sentence [source_sentence]  
the correct answer [correct_answer]  
an id for the news article [news_article_id]  

Use this method to retrieve a set of multiple choice questions. This method has the URL [hostname]/api/multiple_choice_questions. Pass the news article URL to this as an argument. You can also limit the number of question objects in the response by using the limit parameter.

Response

{  
  'num_questions': number of questions that were generated from the url you passed,  
  'questions': the questions object which contains individual question items  
}  

The Question object contains

an id unique to the question item [id]  
the question text [question_text]  
the source sentence [source_sentence]  
the correct answer [correct_answer]  
an id for the news article [news_article_id]  
four possible answer choices [answer_choices]

Use this method if you know the id for a specific question. This method as the URL [hostname]/api/question/<q_id>. The question id is a hash generated by us.

Response

the question associated with the id [question]

Use this method to extract the article from the webpage. This method has the URL [hostname]/api/article. Pass the news article URL to this as an argument. Returns raw text.

Use this method to extract the top sentences from the webpage. This method has the URL [hostname]/api/top_sentences. Pass the news article URL to this as an argument. Returns json.

Response

top sentences from the article [top_sents]

Use this method to extract all sentences from the webpage. This method has the URL [hostname]/api/sentences. Pass the news article URL to this as an argument. Returns json.

Response

all sentences from the article [sents]

Use these simple helper methods to gain feedback about questions. good_question: [hostname]/api/good_question/<q_id> bad_question: [hostname]/api/bad_question/<q_id> Returns json.

Response

success or failed depending on the result of the database operation [status]