Had a rough afternoon trying to get Swagger working on my json api. (I tried Phoenix Swagger and OpenApiSpex.)
Should I look at gRPC or GraphQL?? I’ve never used gRPC, and years ago have had good experience with Absinthe.
I want a ‘self documenting’ API that’s easy to maintain, with good support for multiple client languages. Not so concerned about caching. Seems like any of the three approaches ought to work for my app.
What is the best approach in 2023?
You should probably consult with whoever is going to consume the APIs.
GraphQL is great solution, especially if you manage to make it “flat” and not too much of a nested / looped graph but it’s not being universally loved, especially by native/mobile application developers in my experience, and non-dynamic language programmers, who often rely on code-generation client libraries to consume the API.
gRPC very much similarly so, it’s often a choice that’s presenting a barrier, even bigger than GraphQL.
JSON API, with Swagger UI and documentation is more of a hassle to maintain on Elixir end, but it may be the familiar and easy to use solution by your API consumers.
I personally dislike GraphQL. In all my work in Elixir, Rust and Golang I have never seen one project where the fact that our backend is GraphQL-enabled has not led to a lot of boilerplate and double-schema writing (one in JS for the frontend and one in the backend language). Pragmatically and egotistically speaking only from a programmer’s point of view, GraphQL is a hassle and a fickle princess you have to handle with care in order for it to not fall over.
As much as I hate JS, I’ve only seen GraphQL development be almost frictionless in JS projects. Their ecosystem has it really well covered.
That being said, REST API or gRPC can be an even bigger hassle down the road, they you could start with a REST API relatively quicker than GraphQL (but not by much).
So if I have to pick the lesser evil I’d still go for GraphQL. It allows you do quite a lot and the stricter schema, while very annoying to maintain sometimes, pays for itself tenfold if your project lives to be at least 6 months old or more.
OpenApiSpex is the continuation of the Phoenix Swagger project, so you use it if you want a generic REST API documentation.
I’ve used about half a year ago in a new project and it worked flawlessly, used it with built-in swagger-ui behind an authentication wall. The only main issue I had was that I didn’t understand how to use the specs at first, however it becomes clear when you read from official open api documentation the format of the specs.
Thanks @all for your input. Persuaded by the bitter realism of @dimitarvp, I’ll switch to GraphQL, the least bad option in 2023. 
Still I dream of a world where I don’t have to maintain the schema in three places. Does anyone have experience with GraphQL or Rest/Swagger on the Ash Framework? Is this too good to be true?
I guess everything is a preference. There is no “one size fit all” solution, but I personally love GraphQL and minimizing the data transferred (that is especially important when supporting mobile devices) and no need to write another endpoint just to provide another field.
In my very humble opinion, because of the schemas, it is easier to keep the naming consistency across the whole app.
I never used graphql for anything serious and at my previous project I declined using it because of a single fact: you just move the responsibility of data manipulation to the frontend. At the end of the day you write more code on frontend(mobile) in different languages that is more complex and harder to maintain, at least this is the way I see it in context of the applications I made and make.
GraphQL client complexity…
True. Curl and Wget are hard to beat. But for this app, I’m optimizing for backend developer experience.
Obviously, you are entitled to your opinion, but as I said, if you are supporting a big application you will constantly write APIs that do the same thing, just one more or less field to limit the data usage and end-user experience (because of loading time and memory usage if you transfer data that it is known no to be used).
The trade-off is that you shift the responsibility of knowing what information the front end needs to… the front end. Sounds reasonable to me. Moreover, I would personally refuse to work on a big application if it used REST because of the reasons above.
You are entitled to your own opinion and I respect that, even though I strongly disagree.
We are talking about different use-cases, but let’s not transform this into a conversation about advantages of types, because graphql is not the silver bullet.
I don’t want to be rude, but we work with what we got, at the end of the day if I can make a REST api work better on a project, based on multiple reasons, for example there is a mobile developer that is just a beginner, then that solution will always beat the philosophically correct solution.
Then I would go with rpc cals, give them the cookie and let them connect to your node and do the heavy lifting themselves. 
This argument sometimes comes from bad design of a REST API. See my answer on this other topic:
In resume, when designing a REST API endpoint for a resource nothing stops a developer from accepting a query parameter with the list of fields to be returned in the response, plus the list of sub-resources and their fields:
apibaas.io/some/endpoint?resource=posts:author;title;content,comments:author;content
Now, to group unrelated resources GraphQL as an advantage, but nothing stops you from having an API endpoints like this:
apibaas.io/some/endpoint?resources=categories:title,products:title;description;content;price,promotions:title,description,price,discount
Now, if you say that GraphQL query language looks better in terms of ergonomics I have to agree with you, but REST APIs are superior in terms of enforcing security via OpenAPI specs and prevent an attacker to dump a lot of data in a simple GraphQL request.
Put it simple GraphQL puts convenience over security due to its design. GraphQL is the nightmare of security teams and the dream of frontend devs.
I don’t like GraphQL either, unless it’s with a large team of separated front-end and back-end devs. In that case, though, I’m very happy with Absinthe. I used it for a client project 3 years ago and found myself pleasantly surprised more than once.
I tihnk the more nuanced argument for GraphQL here isn’t that it’s impossible to parameterize REST, it’s just that everybody making their own ad hoc way of doing it is worse DX than having a spec for how to do so.
Yes, there are specifications out there that standardize on some of this, and that might work great for your use case! However it’s hard to beat GraphQL on the flexibility department.
Complexity analysis makes this a pretty solved problem in GraphQL as well. Certainly though I’d say it is more complex to support a public GraphQL API than a public REST API. Nightmare I think overstates the security situation though.
I’m not gonna weigh in here too much on the actual comparison bits but if folks have more questions about GraphQL I’m always happy to answer them as I can!
No API is free. You have to design it. There are a lot of little decisions like: how will you layout the various endpoints in code, how will you validate input, how will you control what is queried and returned, how will you share docs, and so on. A good GraphQL implementation, like Absinthe, could help with a good deal of this.
GraphQL is partly solving for a team communication issue. Once a schema is designed with input from both frontend and backend devs, they can go their separate ways and implement. If you are working in a small team or if the same team works on both frontend and backend, then there is less need for GraphQL.
Just a little context on why I am picky on Security: I work as a Developer Advocate for Mobile App and API Security.
What I see is that more often then not developers and businesses make decisions based on convenience, rather then security, and this affirmation is not targetting directly REST vs GraphQL. It seems that the huge amount of data breaches are slowly changing this mindset for some, but I also observed another pattern of very big businesses treating data breaches and resulting fines and losses as business as usual. They can afford it but medium and small businesses can’t.
In fact, a security breach can lead to a medium or small business to fill for bankruptcy in the following year, or reduce drastically their revenue, due to a loss of trust of their users and consequent move to products offered by the competition. Next time you need to make a decision bear in mind this.
Yes, and OpenAPI specs are the most used one.
To be clear, I am not against anyone or myself using GraphQL I just cannot stand the argument that REST APIs need an extra endpoint for each time one more field needs to be returned. In my opinion, when that is the case, then is just pure bad design of the API, because I would not design such inflexible REST API endpoints for a production API.
So, each team needs to use whatever best feet their needs, but they must be aware that REST API isn’t the elephant in the room, especially for the new generation of developers, and they need to understand the risks they are accepting in terms of security when adopting a GraphQL API.
We will have to agree that we disagree here: REST APIs are easier to secure then GraphQL.
I know that some advances have been made towards securing GraphQL, but they may be costly to be applied in terms of performance, but I may be wrong here.
Yes, and I admitted that in my answer when I said that it has better ergonomics, especially for frontend devs.
The query language is really a strong point in favour of GraphQL.
Same holds true for REST API that use OpenAPI specs.
As far as GraphQL goes then yes, Absinthe is an extremely good library; it mostly stays out of your way. Even when me and the team needed to hook into it while it was doing its stuff… that was surprisingly possible and felt empowering. Annoying to discover and experiment until you get it right, sure, but much better than it being impossible.
I’m not taking a jab at anyone, and as it was already pointed out nothing comes for free. Elixir has one of the best ecosystems out there when it comes to good coverage of doing your own API design and implementation.
I predict that we’ll get some universal schema language akin to C or OCaml header files that contains not only strong and even linear types but also all exposed endpoints, their security limitations, etc.
Or at least I hope that comes to pass because it’s about damn time already.
btw this just popped on HN a few hours ago. Could be a useful read:
I may have a little bit of experience with it
You should give Ash a try, especially if you want to support GraphQL & Rest (our provided json api extension is a spec-compliant JSON:API api). We will also have gRPC someday. The author of OpenApiSpex contributed our open api tooling (still young, but it works).
© Copyright Elixir Forum | Terms | Privacy & Cookies
