Hello, fellow Rails developers and everyone who wants to participate in the discussion. I'm working on a small side project where I want to create a rails API.
I use the TDD approach (at least I try! 😅) and code in small iterations. Now after I created the whole model, validations and basic routes, the moment of truth has come...
I need to choose how my API will look like and what gem is the best to use for Serialization.
After googling and reading some articles, I found that there are a lot of blogs related to Fast JSON API which is now deprecated and kind of replaced by JSON:API Serializer. These gems are following JSON:API specification and force our API response to meet this specification standard.
On the other hand, we have Active Model Serializers. This gem is also deprecated but has another stable version 0.10.
I also found Blueprinter gem. I've never used it before and don't know its limitations.
I'm curious, what are the best practices in building robust REST APIs that are easy to use? Is it better to follow JSON:API specification or create something of your own?
For instance, looks like GitHub or Shopify responses don't follow JSON:API specification.
And if one chooses to create responses not following JSON:API standard, which gem would you prefer to use 🙃?
Top comments (4)
Hi Maryna! REST as you mentioned doesn't really enforce a specification.
Technically any JSON library is fine as it's not inherent about the format.
We use the gem
JSON:APIat Forem, but for internal serialization mostly, the public API doesn't follow the JSON API standard, we use a combination of.to_jsonandJBuilderto render it. We also use Oj as the backend serializer.My recommendation is to document your API with OpenAPI 3. I know there are tools to help with it in Rails, but I haven't tried any.
I'd like to explore Design First APIs in the future.
Thank you so much for sharing this information!
I like using
Ojgem in my projects as well.I will go ahead with not following
JSON:APIstandard for my public API.I was thinking of using
OpenAPI 3for my documentation in future, so thanks for sharing cool articles with me 😄I wasn't sure if there are any gems that support OpenAPI v3 yet, but I see the article is listing some GUI tools, so will check out those as well.
I think it really depends on what you are trying to achieve with your rest API. In a recent project the question came up if we should use a standard spec like JSON:API but then decided to go without it. We took some parts from the spec it but didn't go with the full implementation. In the end it's about how public your API is and how much you'd like to invest into documentation. I'm a fan of as few other gems as possible in my projects.
Makes sense.
Thank you for the insight, agree on the documentation part! This is definitely something I'll need to work on.