(p)repair project – JSON:API specification integration

Questions / Help
, ,
1

Hello,

Long abstract

I made a first post 10 months ago about my project, and my beginnings in programming.

So I’m creating a project from scratch (since about 10 months, with 3 months dedicated on totally other stuff).

I am accompanied by my brother, who is a master full-stack developer (in my eyes, but not only). But he doesn’t get much time, since he is already full-time working for a company, and already have a great professional investment with them.

He guides me on the app architecture, then I write code, push commits and merge requests that he verifies, send me questions and comments back, and so we advance like that.

So we chose Elixir as a programming language, with Phoenix as a framework for the backend. And because the projects turns to be a (native) mobile app at first, we chose FlutterFlow to design and get the frontend quickly working. Then we will be able to get all the generated Dart code from this low-code tool, and to polish the frontend regarding our needs. But it’s not at all a priority for now, as we can get things working fine in a simpler and (most importantly) faster way.

We’ve advanced on backend code, and I learned a lot (and still have a loooooot to learn) about programming.

To be honest, programming is still not a passion (as it is for my brother), but a mean to achieve my vision through a concrete project. But I also admit it can be pleasant to code when you find solutions to problems you encounters, and learning new things everyday is a pleasant journey (but it don’t makes you live, nor makes the world turns better).

Short abstract

We’ve creating a project with:

  • a backend using Elixir - Phoenix
  • a frontend using Dart - Flutter (currently FlutterFlow to gain time)

The frontend communicates with the backend and receives responses through a JSON REST API.

As it is painful to modify API calls on the frontend (even more in a low-code tool I guess, because a lot of actions are done with clics on an interface, so you can’t easily search/replace), we want to stabilize the API.

After researches with my brother, we decided to rely on the JSON:API specification, which looks very complete, to avoid too much thinking on what we need now and should need in the medium-term.

It is also important for us to have a good API documentation for 3 reasons:

  • it is faaaaar easier to integrate API call definitions to FlutterFlow with an OpenApi / Swagger file than without (OpenApi 3.0 required)
  • it is a good mean for us to visualize the current features of our API
  • it would be useful in the future if we want to share our API with third parties

After other researches, we found tools that may be useful to our project:

Questions

What do you think about our API strategy?

Do you have experience / feedbacks on currently using one or many of these libraries?

Do you have other experiences to share on using JSON:API specification on Phoenix?

If we go this way (with these libraries), does some of you already updated PhoenixSwagger to generate OpenApi 3.0 documents instead of 2.0?

EDIT: I’ve just seen this post OpenApiSpex - OpenAPI / Swagger 3.0 for Plug APIs that I haven’t seen in my previous researches. I start to read it. All feedbacks on my case are still very welcomed :slight_smile:

2

Have you considered GraphQL? Absinthe is a very mature library.

2 Likes
3

JSON:API is a good spec. Not a great spec, but AFAIK it’s the best option out there at the moment. Ash users get the benefits automatically through AshJsonApi, which mitigates most of the cost of supporting the spec, but I think even if I was going to hand-write against the spec it would be better than nothing.

2 Likes
4

Thank you for your answers!

@dimitarvp , we’ve considered it, but my brother told me there would be much work to be done on security with a GraphQL API than with a REST API. What do you think of it?

@zachdaniel , thank you for your feedback, my brother also seen Ash Framework with a good eye, and we will probably implement it for our project in the medium term, but maybe not right now before the MVP. Would Ash also be easily compatible with GraphQL the case we would decide to migrate?

5

Possible, but not necessarily. You can still get away with a normal API token but sadly yes, putting the plugs and basically the boilerplate in place that’s required for that to work is more than what you’d do with only plugs.

1 Like
6

Yes, that’s one of the primary benefits of Ash is that you design the application once and the APIs come for free, graphql or json api.

2 Likes
7

@dimitarvp , probably we will continue on a REST API to finalise our first product version quickly… But maybe we will use GraphQL later.

@zachdaniel , it sounds a very practical tool, I will look further if it wouldn’t take to much time to migrate on Ash soon.

8

I naturally am biased, but I don’t want to necessarily make this thread into a pitch for ash, just wanted to provide some context on the json api choice :slight_smile:

1 Like
9

No worries @zachdaniel , it’s always good to exchange, and for me to have feedbacks.

I recently realized how annoying could be repetitive code writing for authorization tests so I got interested into Elixir macros for the first time. I am forced to admit it was worth the time to learn new things and apply them for maybe a full day, rather than writing almost same tests for many controllers. And this is certainly a huge gain of future time when modifications will be needed on these tests for any reason (and it will happen for sure).

I took the time to read your blog articles on declarative design and an incremental approach about it. It seduces me on that way, for sure, even if I’m just a bit scared about my current capabilities to properly write such engines. I think it requires more thinking time. But perhaps it’s the key for implementing new features faster in the future.

And to be honest, my brother is always advocating declarative design (he’s using NixOS, so I am) since many years from now, so maybe it’s already time to upgrade our project code, even before the MVP launch… I’ll try to keep you updated on our project’s choices!

2 Likes