Endpoint Tracking Meta-Ticket

[TangoYankee]

Description

This is a handy summary of seeing which endpoints are documented and implemented.

We created the stable tag to tell the frontend which version of the openapi documentation is actually implemented. However, it depends on every endpoint being implemented in the same order that it was added to the documentation. This meta ticket tracks the order we want to implement the endpoints. Correspondingly, it tells use the order we must add the endpoint documentation to keep the stable tag helpful. We can still write the endpoints in parallel. But, the merge order must match the order shown below. Also, we are free to change the order before we merge the documentation. However, once we merge the documentation, we are committed to that order.

The endpoints are listed in the order of desired implementation. There is a checkbox for when it has been documented and when it has been implemented. Implementation order must follow documentation order to keep the stable tag meaningful. The stable tag will be placed at the latest point in time where the endpoint has been both documented and implemented.

As we merge documentation onto main, let's also track the commit hash where the documentation was added. That will make it easier to move the stable tag to that commit once the endpoint has been implemented.

Endpoint Order

• [x] findAgencies
  • [x] documented
  • [x] implemented
• [x] findCommunityDistrictsByBoroughId
  • [x] documented
  • [x] implemented
• [x] findCityCouncilDistricts
  • [x] documented
  • [x] implemented
• [x] findCapitalProjectsByBoroughIdCommunityDistrictId
  • [x] documented
  • [x] implemented
• [x] findCapitalProjectsByCityCouncilDistrictId
  • [x] documented
  • [x] implemented
• [x] findCapitalProjectByManagingCodeCapitalProjectId
  • [x] documented
  • [x] implemented
• [x] findCapitalProjectTiles
  • [x] documented
  • [x] implemented
• [x] findCapitalCommitmentsByManangingCodeCapitalProjectId
  • [x] documented
  • [x] implemented
• [x] findCommunityDistrictTiles
  • [x] documented
  • [x] implemented
• [x] findCityCouncilDistrictTiles
  • [x] documented
  • [x] implemented

[TangoYankee]

@damonmcc I replaced the individual tickets with this meta ticket on the capital planning project. I thought that would help clean up that project board

[pratishta]

I was looking into how we can indicate that an endpoint has been documented but not implemented. This is so that we 1) don't have to follow a dev flow of needing to only merge in implementation PRs of the preceding documented endpoint, and 2) alleviate the work of having to place the stable tag at latest commit of both documentation and implementation of an endpoint.

Here are some options:

1) We literally use emojis :D and document what that means in our README. The PR with implementation will also be responsible for removing the WIP emoji

2) We use tags. The PR with implementation will also be responsible for removing the Unavailable endpoints tag and replace it with the appropriate tag

3) Using a custom Redocly config file with decorators such as filter-out or following their process for hiding internal APIs. This will require a bit more orchestration like updating package.json with npm commands to bundle and then build the site from the appropriate yaml file for. This process will have to be expanded and rewritten for deploying to prod and/or documented if the front-end is using a locally served API

My thoughts are that if the sole purpose of the stable tag is to inform front-end work, we should use option 1 or 2. An emoji or tag subsection on the html page should be enough to indicate that an endpoint isn't implemented yet. Option 3 seems cool but it seems kinda annoying to have to keep track of multiple yaml files which also defeats the point of using OpenAPI in the first place.

[TangoYankee]

@NYCPlanning/application-engineering, what does everyone think? We'll be all be working with whatever option we go with (whether it's one of these three options or sticking with the stable tag)

[TangoYankee]

Yes, this is ultimate to make it clear to consumers of the API which endpoints are actually available to develop against.

The way we implement frontends is also changing from the way we did it when the stable tag was introduced. When developing the zoning-map-poc, frontend feature creation depended on the endpoints actually being implemented in the API. The stable tag works by configuring the frontend kubb file to point at the version of the OpenAPI documentation that is actually implemented. Consequently, only endpoints that are actually implemented have react-query code generated and available to the developer. The assumptions are 1) We can only develop frontend features using the API 2) Stopping the codegen stops the accidental use of the endpoint

These assumptions are no longer being met. First, we can use tools like mock service worker to fake the endpoints before they are implemented. This decouples frontend and backend development, as we originally intended with our use of OpenAPI. Second, not every API consumer is an internal frontend. The API is consumable by the general public. Some folks are going to read the documentation, try to hit an endpoint having no idea about this obscure 'stable' tag, and be confused when they get a 404.

The stable tag is a headache to manage and it also works against how we want feature development to progress.

With this in mind, let's examine the three options above.

The filter option is neat. But, it relies on hiding the "under progress" endpoints. This works against the philosophy of "document and then implement". The static site is the most human-friendly format for understanding the endpoints. If we're hiding them from the static site, then we're not really documenting them.

The tag and emoji options make sense. First, they communicate the design of the endpoint. This allows developers to start planning for its implementation. Second, they communicate that it is not live yet. Between the two, the emoji is more effective. The tag text blends in with other text making it easy to miss. Also, we will want these endpoints to have their usual tags. This means a developer could find the endpoint under their regular description tag, like "Capital Projects", and not realize that it also belongs to the "Unavailable" tag. Meanwhile, the emoji visually stands out from the text and is prominently featured in the name of the endpoint. Though, could we use construction instead of warning? I think construction captures that the endpoint is a work in progress

TL;DR: A construction emoji would best fit our needs going forward.