Skip to content

Create an endpoint

Jump to bottom
Helen Cao edited this page Jun 25, 2019 · 6 revisions

This is an example of how you add a new data endpoint to the API. I will use the RAD endpoint as an example. This procedure may change as the API evolves.

Create a branch for your work

checkout the most recent develop branch and create a branch for your work:

git checkout develop
git pull origin 
git flow feature start the-name-of-your-feature

Make ofec_ view or materialized view

The website data is usually a mix of FEC data tables. The most common approach to creating a new data resource is creating a materialized view. we preface the resources we make with ofec_ so you can tell the resources serves the website. We refresh our views nightly.

We manage our views with flyway migrations. Write your new view by looking at the number of the most recent migration. You will want to add your work in a new file that starts with "V" then the next integer after the last migration and the discription of your file. For example, if the most recent migration is called V00556__add_important_table.sql then you should name your file something like V00556__add_RAD_contact_view.sql. Grant owner to fec and permissions to fec_read roles.

If you create a view that has another view depending on it, you will want to add the dependency to the manage.py function and flow.py https://github.com/18F/openFEC/blob/develop/manage.py#L289 https://github.com/18F/openFEC/blob/develop/webservices/flow.py

When you are creating new resources:

  • Make sure all the names are human readable and consistent with the names in other public facing resources.
  • Make sure there is an unique index, that is required for updating the materialized view without downtime.
  • Create the resources in /sql_updates will make the script part of the manage.py schema_updates command.
  • If you need to recreate make sure your resource ends in _tmp we use that naming convention to create new resources before drop cascading the current resources and renaming them so they do not end in _tmp.
  • Add indexes to sortable and filterable columns.
  • Full text fields need ts-vector
  • If your table or view has dependencies on another table, add that to webservices/flow.py that is what will
  • example file

Make model

A models are the the source of information about your data for Python. It defines the fields and behaviors of an object. An API endpoint can be made of one or more models.

  • Describe column to sqlalchemy
  • Add documentation
  • Mark which columns have been indexed
  • example file
  • Add to init if making a new file. This is what we use for imports elsewhere.
  • example init

Make args

Arguments are where we define what fields can be sortable and filterable.

  • Fields must have been indexed in the table to be sortable
  • Assign the right field types
  • example args

Make schemas

Schemas are used to format the data served from the API.

Make resource

Resources handle the logic for the API. The following example is from our newer endpoints that inherits from an extensive base class. These are easier to build and extend. Note that some of the older endpoints have more custom code in them.

Add URL

Now, you can add a url for your resource.

Make a test

Test make sure we don't break features as the code evolves.

Create a pull request

Someone on the team will do a check of your code for logic and style review and then pull down your code to try it out locally. Once it has been approved it will be merged into master.

Clone this wiki locally