Writing out an API schema explicitly is good for human understanding and runtime correctness.
We'll need to reference the API both from the TypeScript side and the Python side. Assuming Rust is a pass-through, it doesn't need to know about any API types.
Some references:
My approach on recent projects has been something like this: https://github.com/danvk/crosswalk
- Define your API using a TypeScript
interface
- Use
typescript-json-schema to generate JSON Schema to validate requests/responses at runtime.
- Python dataclasses can be generated using quicktype, though its codegen is not always the best.
I've generally been reluctant to use TypeScript schema tools like zod on projects in the past since they force you into using another bespoke schema language for your types instead of normal TypeScript type syntax. The advantage of zod is that you get runtime and static types without a build step, and you can express things like "a number between 5 and 10" more easily than with TS types. That being said, Zod is very popular and I'd be happy to see how it works in practice. We'd still need to get Python dataclasses out of it, though.
You can also go the other way: define a schema with dataclasses in Python, then use dataclasses-jsonschema to generate JSON Schema from them, and finally json-schema-to-typescript to get a TypeScript interface.
If we define the API in Python or TypeScript, then it's likely that it will feel a bit awkward in the other language.
Writing out an API schema explicitly is good for human understanding and runtime correctness.
We'll need to reference the API both from the TypeScript side and the Python side. Assuming Rust is a pass-through, it doesn't need to know about any API types.
Some references:
My approach on recent projects has been something like this: https://github.com/danvk/crosswalk
interfacetypescript-json-schemato generate JSON Schema to validate requests/responses at runtime.I've generally been reluctant to use TypeScript schema tools like
zodon projects in the past since they force you into using another bespoke schema language for your types instead of normal TypeScript type syntax. The advantage ofzodis that you get runtime and static types without a build step, and you can express things like "a number between 5 and 10" more easily than with TS types. That being said, Zod is very popular and I'd be happy to see how it works in practice. We'd still need to get Python dataclasses out of it, though.You can also go the other way: define a schema with dataclasses in Python, then use
dataclasses-jsonschemato generate JSON Schema from them, and finallyjson-schema-to-typescriptto get a TypeScript interface.If we define the API in Python or TypeScript, then it's likely that it will feel a bit awkward in the other language.