Schedule of API Endpoints

Our API needs a uniform interface for client requests, so we must determine the best way to format our URIs.

Considerations

URL Prefix:

/api/<version_number>/infrastructure

e.g. /api/v0.1.0/infrastructure

Should we lead with primary type or secondary type?

/infrastructure/mines/coal or /infrastructure/coal/mines ?
On some level it makes sense to say -- this is infrastructure, the infrastructure category is mines, and the resource type is coal.

How do we want to handle issues with pluralization?

For example, inter_intrastate pipelines’ primary_type is pipeline, but we want the path to read /infrastructure/pipelines/gas
By convention, API's describe endpoints in the plural form.
Would it be better to just modify everything in the db whose primary type is pipeline to make it pipelines? Which semantic headache is less annoying?
We could also just write a detailed pluralization algorithm, but that can get tricky as more stuff gets added.
We could have a style note that all new infrastructure must have a primary type in the plural form of the word and then make our updates for what we already have in Mongo.

Example of a problem with endpoints following the format:`/infrastructure/primary_type/secondary_type`

Some of our data don't have a secondary type. This is easy to resolve programmatically, but may present issues for our ideal uniform interface
Example: /infrastructure/biodiesel
- Semantically, what is happening here? Biodiesel what? Fuel? Should it actually have a primary type of fuel?
- e.g. we would lead with /infrastructure/fuel/ and have /infrastructure/fuel/biodiesel?
- Would that, however, lead to other problems where we need another type property for gas wells for example?
- For example, requiring three types -- /infrastructure/fuel/wells/gas? Or should we add a category type to cover the infrastructure category?

Pseudocode for an endpoint in the /retrieve dir

Please forgive the mixing python/js. Secondary type is null, so

bp = Blueprint('create', name, url_prefix=URL_PREFIX)

def get_infrastructure():
    if (properties.type.secondary is not None) { 
        url = '/{properties.type.primary}/${properties.type.secondary}'
    } else {
        url = '/{properties.type.primary}' 
    }
    return url



### Examples of tentative endpoints
`/mines` i.e. return all mines
`/mines/coal`
`/underground_storage`
`/underground_storage/gas`
`/pipelines` i.e. show all pipelines
`/pipelines/gas`

List of API Endpoints if we follow the type.primary, type.secondary convention, in plural form

/pipelines
- /pipelines/gas
- /pipelines/oil
- /pipelines/petroleum_product
/mines/
- /mines/coal
/biodiesel
- or /fuel/biodiesel if we add another type
/underground_storage
- /underground_storage/gas
/active_platforms
- /active_platforms/oil_gas
  - This data is not separated between oil and gas, hence the weird secondary type
/teriminals
- /teriminals/petroleum_product
- /teriminals/import
- /teriminals/export
- /teriminals/import_and_export
/refineries
- /refineries/petroleum
/power_plants
- /power_plants/hydroelectric
- /power_plants/coal
- /power_plants/natural_gas
- /power_plants/nuclear
- /power_plants/petroleum
- /power_plants/wind
  - This poses a problem because the legend will read "Wind power plants" rather than "Wind farms."
    - /power_plants/solar
  - This poses a problem because the legend will read "Solar power plants" rather than "Solar PV."
- /power_plants/pumped_storage
  - This isn't an option in the current front-end app but we do have some data for this type
- /power_plants/geothermal
- /power_plants/wood
  - This isn't an option in the app but we do have some data for this type
- /power_plants/other_fossil_gases
  - This isn't an option in the app but we do have some data for this type
/processing_plants
- /processing_plants/gas
/railroads
/strategic_reserves
- /strategic_reserves/petroleum
/shale
- /shale/gas
- /mixed_shale_chalk
- /mixed_shale_chalk/gas
- These ones are weird. My best guess at setting property types left us with something pretty odd.
/wells
- /wells/tx_capcog
  - One issue here is that the original data set didn't provide us with oil and gas wells. Did we find that data elsewhere or did we sanitize what we had to separate it properly?

There are things about some of these that seem funky, and I would definitely love feedback on what I have here. We will need to go into the db and update primary types to be plural, and we may need to do more from there as well. I anticipate that more work needs to be done before we can start actually creating our endpoints.

Endpoints we may need where data is not currently in the database

/wells/gas
/wells/oil
Something for electric. But what is the primary type? transmission_and_distribution_lines? Or just power_lines? electric_lines?
/wind_capacity
- We have this data, but it is not infrastructure, so we have debated whether we should put it into the API or not. Need to determine if semantic reasons are good enough to keep it out, or if we need another collection, or should just keep the file locally. We had the same type of deliberation for state boundaries.

Some Resolutions, 08/26:

Pluralization is fine.
It will be useful eventually to call something up only by secondary type. So then we can create endpoints for all of the secondary types as well.
- So what do we want the app to do if we pass an empty argument? We should have an endpoint for when you just want to specify a secondary type. You could pass an empty object and then a secondary type.
We will leave the wind capacity map out of the API and load it from static json. If we want to retrieve all wind infrastructure we don't want the wind capacity map too.
Active platforms are likely offshore wells. They were somehow differentiated between oil and gas in our more recent data as used on the front end app.
Some interesting tertiary types to consider using are in power plants -- you've got wood -- wood is biofuel. We currently don't have enough info on biofuel, but we throw it in because it's $51B, there's an enormous investment in it, we just can't show it yet. It's useful to have a tertiary type for all biofuels, since there is wood, switchgrass, garbage, etc. People don't need access on the front end but it's useful to tag it on the back end when we need to.
Pipelines also may benefit from a tertiary type, where primary is pipelines, secondary is oil or gas, and then oil can have a tertiary type as well of oil_product.

MongoDB Updates

I went through and made updates to all relevant docs in mongodb to pluralize them.

Completed:

processing_plants
/pipelines
/mines/
/teriminals
/refineries
/power_plants
/railroads
/strategic_reserves
/wells

No action needed

/biodiesel
/underground_storage
/active_platforms
/shale
/shale/gas
/mixed_shale_chalk
/mixed_shale_chalk/gas

RDCEP / energy-maps-api