Advise on managing non-production endpoints/paths (openapi-fetch)

[ViktorPontinen]

Hi,

In our front-end team we're looking to start using openapi-typescript and openapi-fetch in a pretty big project, we have however identified a potential issue that we are unsure on how to resolve. Maybe we're missing something obvious. So looking for advise from the community.

Back-end and front-end are located in separate repos and use different technologies.
Our initial plan is to automate(github actions) OpenAPI yaml generation in back-end on every release to main branch.
Then sync that to our front-end main branch with openapi-typescript automatically as well.

Questions arise when we start talking about feature/chore/bug branches.
In front-end we use trunk-based branching, in back-end they run gitflow with rebasing.

How does one sync proper types to a feature(or other) branch in front-end if back-end has made changes on a feature(or other) branch as well and we want to allow for pararell development in both teams? We excluded the idea of trying to dynamically find the correct back-end branch to sync the OpenAPI from due to overhead and optimistic nature of if, and we want to avoid having the dev specify manually.

How has others/you done it? Keep in mind the PR needs to pass typecheck.

[drwpow]

Great question. I actually built openapi-fetch while working on a system with backend and frontend in 2 different repos. Our solution wasn’t perfect, but we put the OpenAPI spec in a 3rd place. Now that seems on the surface like it just makes the problem worse, but it accomplishes several things:

1. Hosts documentation. We built docs with Redocly off that spec repo for viewing, but we also published the YAML schema to a public URL as part of it (wasn’t a sensitive endpoint, but if it was you could do the same thing just protect it with an auth header). Since we got branch previews, and because openapi-typescript could load from a URL, you could reference any branch of the schema from the backend or frontend (so long as you just made a branch on the schema repo first).
2. Forces better coordination. We realized that the API is a shared contract between backend and frontend, so we’d review changes to the API spec as a team. Or if, say, someone working on the backend needed to add something, they’d open a PR on the spec repo first, and work from that branched YAML schema in their feature branch, so it wouldn’t block them. But overall, it put code in a neutral place where both frontend and backend were mutually encouraged to contribute and review each others’ code. This resulted in better API quality too (my biased opinion, of course, but I think so).
3. Lightens reviews. By separating spec from code, reviewers can review API changes independently from code implementation. There’s less of a chance of something slipping under the radar in a giant diff this way.

The downsides are obvious—it’s more to manage, more friction, and I know devs want to just have “one and done” PRs for changes. But this is one of those things where introducing a little friction in the right ways could be helpful.

Just an idea; obligatory YMMV and this may not work for every setup, and team. But is in an option that works well for some teams.

Another option is polyglot monorepo but I wouldn’t recommend that at all 😅 (I’m a big fan of monolanguage monorepos but polyglot monorepos devolve pretty quickly).

[ViktorPontinen]

Thanks for the reply!

I'll bring this suggestion to the team.

One thing that might be trouble for us with this approach is that the spec is tied to the code on our back-end with decorators. They run Symfony(API Platform) with Swagger(https://api-platform.com/docs/v2.1/core/swagger/), which in turn allows them to automatically generate the spec but keep docs and definitions in code with decorators, so no one is maintaining the Open API manually. There might be ways around this of course and we'll have to do further research.

My current "plan/idea" is to explore a manual sync option with scripts(example workflow below). But was hoping there would be a simpler solution without affecting developer experience (although a properly typed service layer might outweigh this significantly 😃).

Example workflow idea:

1. Back-end dev creates new branch, creates the boilerplate for the endpoint and adds swagger docs in code. (Continues working on business logics etc after initial commit)
2. On commit/pre-commit hook runs Open API generation and adds the spec changes to his/her commit.
3. Front-end dev creates new branch, runs command for example npm run sync-open-api --branch=back-end/branch-name
4. This script loads the Open API spec from the latest commit in the specified back-end branch and passes it through openapi-typescript.
5. Front-end dev now have the proper types.

Usually in our normal workflow, back-end and front-end devs reach a general consensus on the endpoint design before implementation, so quickly adding the boilerplate for a new/changed endpoint and docs should be pretty hasslefree for the BE devs.

Do you think this sounds reasonable?

[drwpow]

Ah I should have figured the schemas were being autogenerated. Your idea makes a lot of sense! I think that’s a great balance of not disrupting the current dev flow you have, but while addressing the issues on the frontend.

Fortunately, too, simply copying a YAML file from one place to another is about the easiest automation you could do, so this seems like the way to go