Closed TangoYankee closed 4 months ago
TylerMatteo
commented
5 months ago @TangoYankee I added a few use cases that I'm confident we'll have to support based on the product requirements we already have but it's not exhaustive. Feel free to add more. Your description covers the specifics of what should be provided for each endpoint. I'm going to follow up with Damon and James for more details on what should be included in the data downloads.
pratishta
commented
5 months ago Endpoints
/projects/projects/<z>/<x>/<y>/.pbfprojects/<mc_id>/<proj_id> -> returns object {description, min_date, max_date, sum_commitments, managing_code, project_id, sponsor_initials[], sponsor_budget_project_types[]} projects/<mc_id>/<proj_id>/commitments -> returns an array of commitments {[{id, commitment_type, date, bl_code, bl_id, sponsor_agency_initials, budget_type, total_value}]} (all stuff from commitments table, join agency_budget, join commitment_fund)/boroughs/<borough_id>/community-districts/<cd_id>/projects/city-council-districts/<ccd_id>/projects/agencies 
TangoYankee
commented
5 months ago Description: Find agencies
Operation Id: findAgencies
Methods: GET
Status codes:
Response body:
Description: Find community districts within a borough
Operation Id: findCommunityDistrictsByBoroughId
Methods: GET
Status codes:
Path parameters:
Response body:
Description: Find paginated capital projects within a specific community district
OperationId: findCapitalProjectsByBoroughIdCommunityDistrictId
Methods: Get
Status codes:
Path parameters:
Query parameters:
Response Body
Description: Find paginated capital project meta data that is useful for looking up specific projects
Operation Id: findCapitalProjects
Methods: GET
Status codes:
Query parameters:
Response Body:
Description: Mapbox Vector Tiles for capital projects
Operation Id: findCapitalProjectTiles
Methods: Get
Status codes:
Path parameters:
Response: An MVT
Description: Details about a specific capital project
Operation Id: findCapitalProject
Methods: Get
Status codes:
Path parameters:
Reponse Body:
Description: Find capital commitments associated with a specific capital project
OperationId: findCapitalCommitmentsByManangingCodeCapitalProjectId
Methods: Get
Status codes:
Path parameters:
Reponse Body:
Description: Find city council districts
Operation Id: findCityCouncilDistricts
Methods: GET
Status codes:
Response body:
Description:
Description: Mapbox Vector Tiles for city council districts
Operation Id: findCityCouncilDistrictTiles
Methods: Get
Status codes:
Path parameters:
Response: An MVT
Description: Find paginated capital projects within a specific city council district
OperationId: findCapitalProjectsByCityCouncilDistrictId
Methods: Get
Status codes:
Path parameters:
Query parameters:
Response Body
Description: Mapbox Vector Tiles for community districts
Operation Id: findCommunityDistrictTiles
Methods: Get
Status codes:
Path parameters:
Response: An MVT
TangoYankee
commented
5 months ago Should we actually be calling these "capital-projects", instead of just "projects"? I'm realizing project is a really generic name. I updated the endpoints with this naming but I'm not married to it yet. Same with capital-commitments
TangoYankee
commented
5 months ago We have two big questions about the MVT endpoints.
1) First, should filtering be accomplished on the front end- meaning that we only need to support endpoints that offer tiles for the whole viewport?
2) Second, we need to share MVT data for fills and labels. Do we want to go with the approach of offering multiple endpoints that each serves a single geometry type? Or, do we want to offer one endpoint that collects the geometries together? I know how to do the first method and I think you were experimenting with the second method?
Either way, it would probably be good to move forward with the other endpoints while we figure out the tiles.
TangoYankee
commented
5 months ago Reading the endpoints back, I think we don't actually need /capital-projects. The mockups only list projects within a geography- this is captured by the district-specific project lists. I do think a /capital-projects endpoint will be helpful if we want to offer a more sophisticated way to filter and access capital projects. However, we don't actually know what we want to support with this endpoint. Do we want to offer spatial filters? Do we want to filter based on zoning-district-class? Do we want to show more details than just the id? Only the future knows!
For now, I think we should remove the /capital-projects endpoint; it's easier to wait and do it the way want the first time, rather than try to change an endpoint we've already made public.
TangoYankee
commented
5 months ago I didn't know what was happening with csv and shape downloads. So, I ended up not messing with that.
TylerMatteo
commented
5 months ago Should we actually be calling these "capital-projects", instead of just "projects"? I'm realizing project is a really generic name. I updated the endpoints with this naming but I'm not married to it yet. Same with
capital-commitments
I'm definitely supportive of favoring capital-projects over projects. It strikes me as an easy way to future proof against potential name collision (lookin' at you, ZAP). "Commitments" are probably specific enough on their own but it wouldn't hurt to do capital-commitments for the sake of consistency.
TylerMatteo
commented
5 months ago 1. First, should filtering be accomplished on the front end- meaning that we only need to support endpoints that offer tiles for the whole viewport?
Let's move forward with the assumption we will be filtering the tiled data on the front end - it seems like a good use for Deck's MaskExtension. If that proves impossible or impracticable, we can revisit filtering tiles at the API level.
TangoYankee
commented
5 months ago I'm definitely supportive of favoring capital-projects over projects. It strikes me as an easy way to future proof against potential name collision (lookin' at you, ZAP). "Commitments" are probably specific enough on their own but it wouldn't hurt to do capital-commitments for the sake of consistency.
I'm thinking we apply the capital-projects and capital-commitments refactor to the table names, as well. It will keep things consistent from the public api to the database.
TylerMatteo
commented
5 months ago Below is a list of the endpoints that we should start with, based on what I think we actually need for an MVP, and feedback/questions on each
No notes. The specifics of what to return might change as requirements become clearer but what you have seems like a sensible default.
Same as above
Grouping these together for obvious reasons. Overall lgtm. We should be able to have them use the same schema for the return type. I have mixed feelings about whether or not nesting the CD one inside the borough is really necessary but we don't need to bike shed that right now.
TangoYankee
commented
5 months ago @TylerMatteo I realized the original list completed omitted the MVT endpoint for community and city council districts. I updated the ticket with an /community-districts/{z}/{x}/{y}.pbf and an /city-council-districts/{z}/{x}/{y}.pbf endpoint
TangoYankee
commented
5 months ago @TylerMatteo Also, realizing that I forgot an endpoint to list all city council districts. This will be required for the city council district geography selector
TylerMatteo
commented
5 months ago One other capital projects endpoint we may need is one that gives you all the projects that intersect with a given coordinate pair, probably with a buffer to be forgiving with point projects. The use case is has to do with selecting projects from the map - projects can overlap, so we need a way to get a list of projects associated with a location, similar to what CPE does.
Still waiting on James for clarity on how exactly our app will handle that use case, so we can de-prioritize this until we know more, just wanted to capture it.
TangoYankee
commented
5 months ago Still waiting on James for clarity on how exactly our app will handle that use case, so we can de-prioritize this until we know more, just wanted to capture it.
Okay, we'll brainstorm implementation once we have more guidance on product
Description
Based on the capital commitment ERD, we will design an API to make the data accessible. This is a precursor to the Open API documentation, which will provide more specifics on how to access the data and what data to expect in return. The result of this ticket will be a list of endpoints, data they will accept as part of the request, and data they should expect in the response. "data" may refer to the HTTP method, HTTP headers, query strings, url parameters, response type, etc. The acceptance criteria below outline key features of the API. However, it is not an exhaustive list and features may be added. Though, feature addition should be done prudently to avoid feature creep.
API Use Cases
Below is a list of use cases that our endpoints will have to support. These should inform the list of endpoints and their details to be compiled for this Issue.