Description
Introduction MiniTwit is an example application that ships with the Flask microframework for Python. It implements a subset of Twitter’s functionality, allowing users to post new messages and follow messages posted by other users. Your business has been running an instance of MiniTwit successfully, but your ● front-end developers want to add a spiffy new Ajax-based UI ● mobile developers want to provide native apps for iOS and Android ● IT people would like to build some custom tools for internal company use, and ● Customer are clamoring for new ways to access the data on your site. In short, it’s time to add a Web API. Test Environment You may use any platform for development, but note that per the Syllabus the test environment for projects in this course is the Ubuntu MATE VM for available from http://michael.shafae.com/#resources. Flask Installation Follow the instructions in the Flask documentation to install Flask. Application Installation and Test To get a copy of MiniTwit, clone the GitHub repository for Flask. The code for MiniTwit is located under examples/minitwit. Follow the instructions in MiniTwit’s README to configure and install the application, initialize the database, run the application, and run the tests. When you reach Step (2) of the README, you will need to either run pip as the superuser, or install MiniTwit into your home directory. Modify the shell command to either: $ sudo pip install –editable . or $ pip install –user –editable . Either choice should work, but the latter is recommended. Once the application is up and running, click around a bit to familiarize yourself with the user interface. Create some users, have them follow each other, and post some messages. Database Population As you work with MiniTwit, you may find that you need to reset the application and drop the database. When that happens, do not waste time by going back and adding users, messages, and followers by hand a second time. Remember: performing simple, repetitive tasks by hand makes you dumber. Create a file population.sql containing SQL INSERT statements to re-populate the database with test data. Modify minitwit.py or mt_api.py (either is acceptable) to add a new Flask CLI command so that you can start over again with two shell commands: $ flask initdb $ flask populatedb Web Service API MiniTwit currently only provides an HTML interface, generated by the server. Create a new Flask application mt_api.py that exposes RESTful URL endpoints for JSON data, rather than generating HTML. Note that you do not (yet) need to modify minitwit.py to use the Web Service API. Endpoint Design Study the MiniTwit code to identify the resources that your Web Service API will need to include and the actions that can be taken for each resource. Then choose appropriate URLs and HTTP Methods for each resources. Your API should follow the principles of RESTful design as described in class and in Chapter 4 of the textbook. You may wish to document the API by creating a table similar to Tables 4-1, 4-2, and 4-3 for each resource. Note that the Twitter API is not a particularly good example of RESTful design. JSON All data sent to and from the API should be in JSON format with the Content-Type application/json. To determine which fields should be present for incoming JSON objects, see the corresponding HTML forms. To determine which fields should be present for outgoing JSON objects, see the context parameters passed to the render_template method. For each API method, document the JSON objects sent in requests or received in replies as in Listing 4-1 in the textbook. HTTP Status Codes Responses from the API should include HTTP status codes appropriate to each method. Responses should be in JSON, not in HTML. Statelessness All requests to the Web Service API must include all information necessary to complete the request; your API may not use the Flask session object to maintain state between requests. The easiest way to do this is probably to use the Flask-BasicAuth extension, subclassing BasicAuth and overriding check_credentials to read from the user table. You may, however wish to experiment with an alternative model such as Flask-JWT. Tips ● Your web browser can be used to test GET methods, but to test POST, PUT, and DELETE, consider using a tool like curl, httpie, or Postman or a library like Requests or the Flask test_client. ● When testing, you might want to use a command-line SQLite client like sqlite3 or a GUI client like DB Browser for SQLite to manage your database. ● On macOS and Linux, you can set environment variables temporarily by including them on the same line as the command you want to run. For example, instead of $ export FLASK_APP=minitwit $ flask run you can type $ FLASK_APP=minitwit flask run This can be useful if you need to switch back and forth between applications (e.g., in order to run initdb in minitwit.py and populatedb in mt_api.py. ● If you’re struggling with the Flask documentation, don’t forget that the list of optional textbooks in the Syllabus includes an book on Flask available online. ● Minitwit’s get_db() function sets up queries to return sqlite3.Row objects, which can be treated as either a tuple or a dictionary, but can’t (by default) be serialized as JSON. To turn a sqlite3.Row into a real dictionary, try dict(). ● If you have a list of objects (e.g., sqlite3.Rows) and you want to run a function (e.g., dict()) on each item in the list, try using map() or a list comprehension. ● If you want to run minitwit.py and mt_api.py at the same time, you’ll need to run them on different ports (e.g., 5000 and 5001). To see the command-line arguments to do this, run $ flask run –help ● If you try to run the tests for Minitwit on the Ubuntu MATE VM, you may encounter the following error message $ python setup.py test running pytest Traceback (most recent call last): File “setup.py”, line 14, in ‘pytest’, File “/usr/lib/python2.7/distutils/core.py”, line 151, in setup dist.run_commands() File “/usr/lib/python2.7/distutils/dist.py”, line 953, in run_commands self.run_command(cmd) File “/usr/lib/python2.7/distutils/dist.py”, line 972, in run_command cmd_obj.run() File “build/bdist.linux-x86_64/egg/ptr.py”, line 157, in run File “build/bdist.linux-x86_64/egg/ptr.py”, line 118, in install_dists AttributeError: class test has no attribute ‘install_dists’ In order to run the tests successfully, you will need to uninstall the version of the Python setuptools package included with the operating system install a newer version, then retry the tests: $ sudo apt remove -y python-setuptools $ pip install setuptools $ python setup.py test Submission Turn in the code for your project by placing population.sql, mt_api.py, modified minitwit.py (if necessary) and documentation for the API in the project1/ subdirectory of the folder that will be shared with you on Dropbox. You may work alone, or make a single submission for a team of 2-3 students. If you work in a team, make only one submission. To complete your submission, print the following sheet, fill out the spaces below, and submit it to the professor in class by the deadline. Failure to follow the instructions exactly will incur a 10% penalty on the grade for this project for all students on the team. Project Submission CPSC 476, Section 1 Project Number ____________________ Names of up to three students for this submission 1. _____________________________________________________________________ 2. _____________________________________________________________________ 3. _____________________________________________________________________ CSUF email of the Dropbox account containing the project files for this submission ________________________________________@csu.fullerton.edu Comments on your submission ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________
