/freefrom-map-backend

Primary LanguagePython

FreeFrom Map Backend

Overview

Welcome to the FreeFrom Map project backend! This page is under construction so expect more information soon.

Local Development Setup

This is a Python Flask app.

Set up environment variables

Use the provided template to set up a .env file with some environment variables you'll need:

cp .env.template .env

.env is included in the .gitignore for this repo and won't be included when you commit your changes.

Setup Instructions

This app can be set up either locally or within docker.

Follow these steps to setup and run it locally

Follow these steps to setup and run it in docker

Local Setup

Install Python

If you don't already have it installed, install Python 3. You can check that you have it installed using this command:

python3 --version

This should return something like Python 3.7.3.

Install Postgres

Install and run a PostgreSQL on your computer.

Set up database roles

  1. Start a Postgres client session: psql
  2. Create a new user: create user "freefrom_map_user";
  3. Create a database: create database "freefrom_map_dev";
  4. Give the user permissions on your database: grant all privileges on database freefrom_map_dev to freefrom_map_user;
  5. Quit psql: \q

Set up environment variables

Use the provided template to set up a .env file with some environment variables you'll need:

cp .env.template .env

.env is included in the .gitignore for this repo and won't be included when you commit your changes.

While .env.template contains some non-sensitive environment variables, there are a few that you'll need to get from the team. Ask in the #proj-freefrom-map-dev channel for these variables.

Start the virtual environment (aka venv)

We use venv to ensure that every developer is using the same dependency versions.

python3 -m venv env
source env/bin/activate

Now, when you run which python, you should get something like: /path/to/your/repo/env/bin/python. You can deactivate the venv at any time by running deactivate.

You only have to run python3 -m venv env once, but you should run source env/bin/activate every time you work on this repository.

Install the requirements

pip3 install -r requirements.txt

Migrate the database

python3 manage.py db migrate
python3 manage.py db upgrade

If you receive a "Target database is not up to date." error, try python3 manage.py db stamp head

Import seed data

Run the following script to clear your database and re-import all seed data:

python import_script.py

Running the application

Run the application with the following command:

python3 manage.py runserver

Then, in your browser, navigate to localhost:5000/. You should see the message "Hello world!" on your screen.

Docker Setup

  1. Set up your local .env with the following DATABASE_URL="postgresql://freefrom_map_user:password@db/freefrom_map_dev"
  2. Install docker (verify with docker --version)
  3. Run docker-compose up in the directory
  4. Pull up http://localhost:5001/categories to view an empty array Optional you can insert a record into the endpoint by connecting to the db and inserting a new record into the categories table. To ssh and connect to psql, you'll run:
docker exec -it freefrom_map_db /bin/sh
psql -U freefrom_map_user -d freefrom_map_dev

Insert new record into categories table, pull it up again via the fetching the endpoint again.

Docker Tips

If you need to shell into a container, either the app or db, you can run: docker exec -it freefrom_map_app /bin/sh and you will enter into a shell. This is handy if you prefer psql over a Database IDE, or need to hop on the containers to check something.

Running tests

Run tests with the following command:

python3 -m unittest

If in docker, you can run:

docker exec -it freefrom_map_app python -m unittest

Linting

Before merging your code, check that it passes the linter (PEP8 style):

flake8

API Reference

The following section describes the FreeFrom map backend API. All responses will be formatted as JSON, and all request bodies should be provided as JSON.

Authentication

All endpoints that create and update resources require that an authentication token be passed in the request header. To acquire an authentication token, you must request one from Auth0 using the FreeFrom Map client id and secret. (Please post in the freefrom-map-dev Slack channel if you need access to the Auth0 tenant.) To add the authentication token to your API request, add it to the Authorization header in the format Bearer <token>, where "" is replaced with the authentication token.

States

A state has the following fields:

Name Type Notes
code String Primary key (e.g. "NY")
name String
innovative_idea String
honorable_mention String
grade StateGrade The most recent grade for the state.
category_grades [StateCategoryGrade] The most recent grade for each category.
criterion_scores [Score] The most recent score for each criterion.
links [Link]

GET /states

This endpoint returns information about all 50 states and DC.

GET /states/{code}

This endpoint returns the state corresponding to the state code provided in the request. If no state with that code exists, it will return a 404 response code.

PUT /states/{code} (UPCOMING)

This endpoint updates the state corresponding to the state code provided in the request. It requires authentication and accepts a JSON body with the following format:

Name Type Notes
innovative_idea String Optional.
honorable_mention String Optional.
grade Integer Optional. One of (-1, 0, 1, 2, 3)
category_grades Array Optional. An array whose elements are objects in the format {category_id: ..., grade:...}. Every category_id must be the id of an active category. Every grade must be an integer between -1 and 3.
links Array Optional. An array whose elements are objects in the format {category_id: ..., text: ..., url: ..., active: ...}. See the Links documentation for information on each of these fields.
scores Array Optional. An array whose elements are objects in the format {category_id: ..., meets_criterion: ...}. See the Scores documentation for information on each of these fields.

Note that it is not possible to update a state's name or code.

Categories

A category represents a group of criteria in the map scorecard. A category has the following fields:

Name Type Notes
id Integer Primary key
title String
help_text String
active Boolean

GET /categories

This endpoint returns a list of all existing categories. It will return an empty array if no categories exist.

Accepts an optional query paramater withCriteria. If withCriteria=true is provided, this will return an array of the categories' criteria in the response body.

GET /categories/{id}

This endpoint returns one category corresponding to the id provided in the request. If no category with that id exists, it will return a 404 response code.

Accepts an optional query paramater withCriteria. If withCriteria=true is provided, this will return an array of the category's criteria in the response body.

POST /categories

This endpoint creates a category. It requires authentication. It accepts a JSON body with the following format:

Name Type Notes
title String Optional.
help_text String Optional.
active Boolean Optional. Defaults to true. Passing in false will create a category that is deactivated. Subcategories cannot be reactivated once they have been deactivated.

PUT /categories/{id}

This endpoint changes a category's details. It requires authentication. It accepts a JSON body with the following format:

Name Type Notes
title String Optional.
help_text String Optional.
active Boolean Optional. Once a category is deactivated, it cannot be reactivated.

Criteria

A criterion represents one measure in the state scorecard to determine whether a state has strong survivor wealth policies.

Name Type Notes
id Integer Primary key
category_id Integer Foreign key
title String
recommendation_text String
help_text String
active Boolean

GET /criteria

This endpoint returns a list of all existing criteria. It will return an empty array if no criteria exist.

GET /criteria/{id}

This endpoint returns one criterion corresponding to the id provided in the request. If no criterion with that id exists, it will return a 404 response code.

POST /criteria

This endpoint creates a criterion. It requires authentication. It accepts a JSON body with the following format:

Name Type Notes
category_id Integer Required. The category ID to which the criterion is related.
title String Optional.
recommendation_text String Optional.
help_text String Optional.
adverse Boolean Optional. Defaults to false.
active Boolean Optional. Defaults to true. Passing in false will create a criterion that is deactivated. Criteria cannot be reactivated once they have been deactivated.

PUT /criteria/{id}

This endpoint changes a criterion's details. It requires authentication. It accepts a JSON body with the following format:

Name Type Notes
category_id Integer Optional. The category ID to which the criterion is related. This cannot be changed, and will return a 400 if it differs from the existing value.
title String Optional.
recommendation_text String Optional.
help_text String Optional.
adverse Boolean Optional. Defaults to false.
active Boolean Optional. Passing in false will deactivate the criterion. Criteria cannot be reactivated once they have been deactivated.

Links

A link represents a web link to an external resource relating to a state and category.

Name Type Notes
id Integer Primary key
category_id Integer Foreign key
state_code String Foreign key
type String
text String
url String
active Boolean

GET /links

This endpoint returns a list of all existing links. It will return an empty array if no links exist.

GET /links/{id}

This endpoint returns one link corresponding to the id provided in the request. If no link with that id exists, it will return a 404 response code.

POST /links

This endpoint creates a link. It requires authentication. It accepts a JSON body with the following format:

Name Type Notes
category_id Integer Required. The id of the category to which the category is related.
state_code String Required. The state to which the category is related.
type String Required. One of ("resource_link", "honorable_mention", "innovative_policy_idea").
text String Optional.
url String Optional.
active Boolean Optional. Defaults to true. Passing in false will create a deactivated link. Links cannot be reactivated once they have been deactivated.

PUT /links/{id}

This endpoint changes a link's details. It requires authentication. It accepts a JSON body with the following format:

Name Type Notes
category_id Integer Optional. The id of the category to which the category is related. This cannot be changed, and will return a 400 if it differs from the existing value.
state_code String Optional. The state to which the category is related. This cannot be changed, and will return a 400 if it differs from the existing value.
type String Optional. One of ("resource_link", "honorable_mention", "innovative_policy_idea"). This cannot be changed, and will return a 400 if it differs from the existing value.
text String Optional.
url String Optional.
active Boolean Optional. Passing in false will create a deactivated link. Links cannot be reactivated once they have been deactivated.

Scores

A score represents whether a state meets a certain criteria.

Name Type Notes
id Integer Primary key
state_code String Foreign key
criterion_id Integer Foreign key
meets_criterion String One of ('yes', 'no', 'maybe')

POST /scores

This endpoint creates a new score. Note that scores CANNOT be updated, only overwritten. To overwrite a score, create a new score for the same state and criterion.

This endpoint requires authentication. It accepts a JSON body with the following format:

Name Type Notes
state_code String Required. The state code to which the score is related.
criterion_id Integer Required. The criterion to which the score is related.
meets_criterion String Required. Whether the state meets the criterion. One of 'yes', 'no', 'maybe'.

Grades

A state grade represents the overall grade assigned to a state based on their survivor wealth policies.

Name Type Notes
id Integer Primary key
state_code String Foreign key
grade Integer One of (-1, 0, 1, 2, 3)

A state category grade represents the grade assigned to a state based on a specific category.

Name Type Notes
id Integer Primary key
state_code String Foreign key
category_id Integer Foreign key
grade Integer One of (-1, 0, 1, 2, 3)

GET /grades/{code}

Returns the state's overall grade, and its grades for each category. If no state with that code exists, it will return a 404 response code.

Forms

A form represents any one of the forms found on the FreeFrom Map frontend. The forms include:

  • Give Feedback
  • Report Missing or Outdated Information
  • Partner with FreeFrom
  • Build Collective Survivor Power
  • Share your Policy Ideas

These endpoints don't require authentication. Note that form submissions cannot be updated or overwritten.

POST /forms/feedback

This endpoint writes to the 'Give Feedback' sheet, and sends an email notification to the FreeFrom staff.

All fields are optional, and values will be written to the sheet as plain text.

Request

Name Type Question Notes
useful String "Was this tool useful?" Optional.
useful_desc String "Can you tell us more about how the tool was or was not useful for you?" Optional.
learned String "Did you learn anything about policies related to survivor wealth from the tool?" Optional.
usage_plan [String] "How do you plan to use this tool?" Optional.
suggestions String "What can be improved or changed?" Optional.

Response

Returns a JSON object representing the data that was written to the Google Sheet. If a field was not provided, its value will be an empty string. Note that usage_plan will be returned as a string instead of an array.

{
    "form": "feedback",
    "timestamp": "2021-01-18T03:40:56.438Z",
    "useful": "Yes",
    "useful_desc": "Nice visuals!",
    "learned": "I learned about my state's policies.",
    // CSV string of input array
    "usage_plan": "As an advocacy tool, Self-educating",
    "suggestions": "Keep it up!"
}

POST /forms/report_missing_info

This endpoint writes to the 'Report Missing or Outdated Information' sheet.

All fields are optional, and values will be written to the sheet as plain text.

Request

Name Type Question Notes
information String "What information is missing our outdated?" Optional.
email String "Your email" Optional.

Response

Returns a JSON object representing the data that was written to the Google Sheet. If a field was not provided, its value will be an empty string.

{
    "form": "report_missing_info",
    "timestamp": "2021-01-18T03:40:56.438Z",
    "information": "Policy X was updated last month",
    "email": "example@email.com"
}

POST /forms/partner_with_freefrom

This endpoint writes to the 'Partner with FreeFrom' sheet.

All fields are optional, and values will be written to the sheet as plain text.

Request

Name Type Question Notes
name String "Your name" Optional.
email String "Your email" Optional.
pronouns String "Your pronouns" Optional.
organization String "Your organization" Optional.
title String "Your title" Optional.
state String "State" Optional.
goals [String] "How would you like to partner with FreeFrom?" Optional.
process_phase [String] "What phase of the process are you in?" Optional.

Response

Returns a JSON object representing the data that was written to the Google Sheet. If a field was not provided, its value will be an empty string. Note that goals and process_phase will be returned as a string instead of an array.

{
    "form": "partner_with_freefrom",
    "timestamp": "2021-01-18T03:40:56.438Z",
    "name": "",
    "email": "",
    "pronouns": "",
    "organization": "",
    "title": "",
    "state": "",
    // CSV string of input array
    "goals": "Request a policy innovation sprint, Help with drafting legislation",
    // CSV string of input array
    "process_phase": "I need help getting a bill to the finish line"
}

POST /forms/build_collective_survivor_power

This endpoint writes to the 'Build Collective Survivor Power' sheet.

All fields are optional, and values will be written to the sheet as plain text.

Request

Name Type Question Notes
name String "Your name" Optional.
pronouns String "Your pronouns" Optional.
interests [String] "Which of the following are you interested in?" Optional.
contact_preference String "The safest way to contact you is..." Optional.
phone String "Your phone number" Optional.
email String "Your email" Optional.

Response

Returns a JSON object representing the data that was written to the Google Sheet. If a field was not provided, its value will be an empty string.

{
    "form": "partner_with_freefrom",
    "timestamp": "2021-01-18T03:40:56.438Z",
    "name": "",
    "pronouns": "",
    // CSV string of input array
    "interests": "Learning how to be a policy advocate in my state, Connecting with other sruvivors in my state",
    "contact_preference": "",
    "phone": "",
    "email": "",
}

POST /forms/policy_ideas

This endpoint writes to the 'Share your Policy Ideas' sheet.

All fields are optional, and values will be written to the sheet as plain text.

Request

Name Type Question Notes
prioritize_policies String "What policies and issues should FreeFrom prioritize?" Optional.
missing_policies String "What policies and issues are important to you but are not included on the map?" Optional.
state String "Your state" Optional.
name String "Your name" Optional.
pronouns String "Your pronouns" Optional.
email String "Your email" Optional.

Response

Returns a JSON object representing the data that was written to the Google Sheet. If a field was not provided, its value will be an empty string.

{
    "form": "policy_ideas",
    "timestamp": "2021-01-18T03:40:56.438Z",
    "prioritize_policies": "",
    "missing_policies": "",
    "state": "",
    "name": "",
    "pronouns": "",
    "email": ""
}