Should the API definitions be source-controlled?

[wkurniawan07]

Currently, we ask frontend devs to generate the API definitions from the backend with the command ./gradlew generateTypes.

This certainly works and has served us well, but there has always been an alternative: to commit the API definitions in the source control, and shift the burden of updating to whoever's updating API definitions instead.

Commit API definitions in source control	Devs generate API definitions on their own
(+) One less step for devs.	(-) One more step for devs, and compounded when there are updates upstream. Has resulted in support requests.
(+) Burden is on change-making dev, who is just one person at a time.	(-) Burden is on change-receiving devs, who are many at a time.
(-) Can get out of sync, but some automation should be able to check/prevent this.	(+) Will not get out of sync, at least in CI.

Quite clearly, the benefit of committing API definitions in source control outweighs the cost, granted the synchronization can be guarded (which is a very strict condition that may not be so easily fulfilled). Is it time to shift the practice?

[daongochieu2810]

@wkurniawan07 do you mean that:

• src/web/types/api-*.ts should be added to git
• Backend devs have to manually update these files (e.g using ./gradlew generateTypes) instead of frontend devs
  ?
  If so, then I think its a good idea

[samuelfangjw]

which is a very strict condition that may not be so easily fulfilled

I'm in support of this proposal (have answered many support issues related to this) but was wondering if you had any examples where the above condition may not be easily fulfilled? Not very clear to me why this is the case. @wkurniawan07

[wkurniawan07]

In essence, we need a check such that the generated files are up-to-date. A naive solution will be running the ./gradlew generateTypes command in one of the CI workflows and fail if there is a git diff. In and of itself it's straightforward to do (simple shell script), but we now need to make sure that anyone updating the definitions need to produce the exact same output (as the CI): down to the order of classes being generated, spacing, comments, etc.

Maybe I'm just very pragmatic, or maybe there is a better solution, but I think you get the point.

[samuelfangjw]

Ok i get it now. Misunderstood the original comment, thought you were trying to say something else. thanks!