Use Open API schema. You can define data models and endpoints or just the models, I do this at work. Then generate your code using openapi-generator.
this post was submitted on 08 Oct 2024
20 points (95.5% liked)
Programming
17145 readers
533 users here now
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
- Follow the programming.dev instance rules
- Keep content related to programming in some way
- If you're posting long videos try to add in some form of tldr for those who don't want to watch videos
Wormhole
Follow the wormhole through a path of communities !webdev@programming.dev
founded 1 year ago
MODERATORS
Do you happen to do this in Ruby on Rails? I don’t know what happened but it seems like Swagger, JSON:API, and the serializers/deserializes are all abandoned.
For personal projects I use GraphQL for everything, I’m not a fan of REST these days. Let me define a schema and let clients screw around with the data. I just won’t waste the time anymore despite the performance impact everyone might cry about.
Two rules of thumb that I've found useful:
- Introduce a version field top-level. If necessary, you can introduce a version 2, but keep the parser for version 1 around.
- You want to err on the side of using objects in place of single values, because you can add fields to an object without breaking backwards compatibility.
I can’t speak to your framework specifically, but:
I’m assuming this is a REST API. I would suggest versioning the API, like /api/v1 for example.
It’s funny, I’m currently dealing with this at work. The old API was just /api but on the backend we’ve mapped it to API::V1 (Ruby). It gets a little pesky backporting things to the older API so it’s good to start with a solid foundation as much as possible.
Something else I might suggest: use a good serializer and deserializer. You don’t want to muck up your models with crazy translations for everything: having a middle layer to perform that has been so, so beneficial to us.