RESTful API Project - Freebie Finder

The Project

We will now be using a proper back-end API to access our data. We will use the RESTful architectural style to accomplish this. You will have a new group, and a new project.

Teams

You will find your teams in gitlab, and project assignments are the same as for the DB project(s)

Language Choice

The technology stack for this project will be:

  • Python 3.9

  • Flask web framework

  • Flask-RESTful library

  • Requests library for HTTP testing

  • PostgreSQL 14 database

  • psycopg2 for PostgreSQL interaction

  • You need to make sure this runs on the GitLab CI. The instructor and TA are well-versed in Docker and can help you on this, but ultimately this is on you.

  • You must use HTTP-based automated tests on the CI. Our default setup instructions use Python and the Requests library. If you use other libraries with Python, that is ok, but you are responsible for making sure everything works in the environment.

  • All DB work must follow expected DB practices and good use of SQL commands.

Setup

Follow our RESTful setup instructions.

Tips and Tools

  • Python’s unittest library is built-in, but there are other compatible libraries that do more. One other is pytest as an alternative. Your tests are exactly the same, just install it and run pytest instead of python -m unittest. A particularly helpful option is pytest --pdb which invokes a debugger on failed unit test.
  • Speaking of debuggers, the breakpoint() method is available in Python everywhere. Just run it near your broken code and when Python encounters it, your code will drop into a debugging console.
  • The output of our RESTful APIs will be in JSON. You can install a browser extension that will automatically format JSON for you so that you can see and traverse the output easier.

The setup instructions for REST are here. Read on for details on the REST Rideshare project.

REST1: Basic Resources and Resource Methods

We will still be following the merge request and tagging pattern. Please tag your code as rest1 on the master branch when it is merged.

In this initial iteration, we’re looking to get the basics working. We will build on the prior project, but instead of making direct DB SQL calls, we will build an API using REST, and your client code (your unit tests) will call the API to use the DB. This also means that you must initialize your DB (load the tables) from the server side (not from your client side unit tests). Review the setup code to see how this is done. Take the data-sets you had in the DB project and use (or adapt) that as necessary for the REST project. In addition, we’ll be looking at getting a few types of resource methods working, to perform the following functions

  • List all neighbor account information,
  • List all communities
  • List the feed of a given neighbor account.

These are not the actual APIs, they are the descriptive names of the functionality provided by the APIs.

Remember that RESTful APIs operate on resources. In the case of Freebie data, the resource will typically map to one of the tables in your Freebie DB. The APIs, will be various operations on the table(s).

For example, List All Account Information could look like /accounts and would return all the the rows and columns from the account table.

List all communities could look like /communities and would return all data related to rides. This could be from one table, or multiple tables (depending on how you set up your DB). It is up to your work figure out the appropriate way. You may even decide to modify your schema as you investigate how to implement the API.

Finally, Show the feed about a specific account would return details on one specific row. The API could either be /feed/{id}, where id would be the primary key of the desired row and is part of the URL, or could be /feed?id={id}, where id is the primary key or the account you want, but the information is sent as a query string for the API.

To implement the functionality, use the above information to name your resources, and then create endpoints and resource methods for those resources. All responses must be in JSON format and follow the RESTful guidelines.

Test Case Sketches

  • Implement tests that cover at least the following scenarios and match the stated results:
  • When calling the API for List All Account Information, you should get an array with N different entries in it. Pre-calculate (based on your data) how many rows should exist and make sure the API returns that many rows.
  • Similarly, when calling the API for List all communities you should get a fixed (correct) number of rows.
  • If you call the Show details about a specific account API, your unit test should confirm that the data returned is what you would expect (again, you will need to work that out ahead of time).
  • If you call Show details about a specific account with an id that does not exist, you should get an empty list back.

Grading REST1 (40 points)

  • (15pts) APIs correctly implemented
  • (15pts) Test cases implemented & pass
  • (05pts) RESTful API standards followed
  • (05pts) Good code maintainability and quality

Grading note: If you have not finished your DB project, then work with what you have. In the spirit of Don’t Break the Build, you should have some sort of working database system. We won’t take off points for functionality asked for in the DB part of the project, just the RESTful interface to it.

REST2: CRUD

Clarification (Meneely sections only)
Note for Spring 2023: just CRUD is required, not authentication. If you see any reference to authentication, please ignore.

Create a branch rest2-dev. Please tag your code as rest2 on the master branch when it is merged.

This iteration, you will need to implement basic CRUD operations to your data. Add those actions to your RESTful API using those conventions.

You will create RESTful APIs for the following functions

  1. Add a user (with all their information). This would be POST. Parameters should be in the BODY (i.e. not part of the URL)
  2. Edit a users information. This would be a PUT to do a SQL UPDATE. Again, parameters in the BODY
  3. Remove a user. This is a DELETE. Consider how to identify the user
  4. List a user’s wishes, with a parameter for the maximum number of entries returned. This is a GET. Your choice on other parameters

Test Cases

In each test case, print out (clearly), the test being run and the result of the test. If there are multiple steps in a test case, list the steps/ results as they occur. Make sure you handle the results without crashing!

  • You can add a new user with a password and any other user information
  • If a user already exists, the add user fails
  • You can edit a users information; if you try to edit a non-existent user, the API fails
  • You can remove a user; again, if the user doesn’t exist, the API fails
  • If you try to remove a user (who exists), and don’t have the correct authentication session key, the API fails
  • You can list wishes, and specify a maximum number to return. Make sure you have enough wishes in the DB to test this properly
  • You can add an item. Consider placement of parameters.
  • In all cases of failure, the API must return a reasonable error, and your unit test must display a human readable message for the error.

Key Decisions

  • What are the conventions for CRUD operations based on your existing resource?
  • Does it make sense to refactor the meaning of your resource to better fit RESTful conventions?
  • What will be the structure of the APIs? How will you pass the arguments?

Grading REST2 (60 points)

  • (20pts) CRUD operations work
  • (30pts) Test cases implemented and pass
  • (05pts) RESTful API standards followed
  • (05pts) Good code maintainability and quality