It's really validating to see Yelp putting a GraphQL API out there as there were a number of questions on whether or not GraphQL made sense as we approached introducing a new API. We (Kiva) also just released our own GraphQL API, though very much in "Beta" it is available at https://api.kivaws.org/graphql with some general API info at https://build.kiva.org
We're still working on documentation among other things before further publicizing it. Hope to take lessons from Yelp and others on best practices with it.
I'm not going to lie, this is the first time I've heard of Kiva. Can you talk about some of the reasons why you chose GraphQL and what some of the technical problems that you've solved that were drastically easier in GraphQL vs REST? I'm trying to decide if it's worthwhile internally to consider a GraphQL API build out, but I'd like to get others perspectives on some of the problems that have been significantly easier to solve, and what was surprisingly more difficult.
There's nothing that you can do with a RESTful api that can't be done with GraphQL. If you wanted to you could build a RESTful GraphQL api -- we did this at my previous company.
GraphQL allows you to do things though like query for nested data structures without making round trips, require typed arguments for queries, and pass arguments to specific fields, things that would take a bit of doing with a non-GraphQL api.
It's certainly not perfect, for example I at least have found query tuning for large nested queries to be a bit more complicated than I'd like it to be, but overall I've had a really positive experience with it and unless I have a good reason not to will be using it for any apis I'm building going forward.
"There's nothing that you can do with a RESTful api that can't be done with GraphQL"
We discussed GraphQL internally, and came to the conclusion that it mostly makes sense as a performance optimization, which was its original use case, and not as an "alternative" to REST APIs.
Drawbacks:
- you loose the ability to easily cache
- your API is more strongly coupled to your data model, which makes evolving it more difficult
So GraphQL makes sense when
- data size / performance is key
- the app is mature and the data model doesn't change very much
We have struggled from performance perspective because we have a relational database at the back. GraphQL has been limited our overall use of JOINS which means multiple queries to fetch data for different data which could've been fetched in a single JOIN query.
If your database is PostgreSQL (which it should be :P) then https://subzero.cloud might solve that for you. Each GraphQL request is translated to a single database query.
The other non-obvious thing is it has been easier to introduce people to use, especially newer programmers. Being able to walk through examples in the browser, all on the same endpoint, just makes it a lot easier for sharing the concept of getting data. Though it may speak to the fact that our audience is primarily people seeking data, not trying to perform actions.
Much appreciated! And the other users comment was super helpful!
I wonder if there would be any interest(or even feasibility) in implementing a REST api data explorer that wraps the REST Api into a GraphQL endpoint so you can have similar discoverability without having to rewrite your entire back end.
Nice to see some technical leadership from Yelp. A tight partnership with 3rd party developers may be a nice way to go up against Google My Business and Bing Places.
If anyone from Yelp engineering is reading this, I'd love to see a major player get behind some standard for uniquely identifying places on which we could join public and private place-based datasets. I like mapcodes: http://www.mapcode.com/
Mapcode doesn't identify a place/business/venue, it identifies a location on earth. If the building moves or a business changes offices then the Mapcode changes, too.
Take a look at Mapzen's gazetteer project "Whose on First". It aims to generate a unique identifier (and store with it concordances for other venue IDs, opening hours, images, etc.) for every venue on earth and is designed to handle situations where a business is started, changes location, or closes.
Very cool! Business (vs. what I call place) is interesting, indeed. I'm working in local media with 150+ year content archives so for this ask I'm more interested in telling the story about a location on earth then the business that currently occupies it. Businesses come and go (or move around) but looking at a single place on earth can be quite the storytelling opportunity too!
Their api doesn't support querying for more than 3 reviews, have ids on reviews, or for any business to authorize your app to enable inline replies. All of which can be done is Google My Business and Facebook apis so I don't think this is anything more than catchup.
Love seeing a public GraphQL API out there - my company is very interested in also using GraphQL to power the new version of our API sometime this year, it looks like an awesome way to bring customizable endpoints to the end user.
Is there any information on challenges developers have found with GraphQL out there?
I'm going to try to do some follow up posts in the next few weeks around building this and I'll work to incorporate some of that in there. It was definitely interesting getting this going.
It looks like the error on that page is asking you to create an API account and authenticate. So maybe not an error in the API itself, but an oversight in documentation?
The guy that posted this makes an amazing python package with an additional package for django called graphene and it pretty much handles everything automatically inferring from you django models, it's amazing. I wrote a boilerplate that got me hired and now we are in the process of building out a graphql + Relay Modern app!
I did some OData a few years ago when it was hip & trendy in .NET land. Right when Facebook announced GraphQL I got a deja vu - our problem with OData was that while the query syntax was awesome, making a server endpoint for it was super hard (unless you happened to be 100% entity framework and wanted all REST data to CRUD straight into the DB and back - which is of course never the case).
I now see people on HN have very similar complaints about GraphQL - how its power and flexibility makes making a performant and secure GraphQL backend significantly harder than making an oldschool REST API backend.
We ended up regex-parsing the OData query fragments that our app happened to use and made it work. We felt dirty for months after, though.
Does anyone have experience with both? Is GraphQL any better than OData in server-side implementability?
> I now see people on HN have very similar complaints about GraphQL - how its power and flexibility makes making a performant and secure GraphQL backend significantly harder than making an oldschool REST API backend.
I'm curious to learn about people who have had this kind of experience with GraphQL, can you please share a link?
> Does anyone have experience with both? Is GraphQL any better than OData in server-side implementability?
OData is complicated, in part, because it includes semantics for querying collections. In GraphQL, it's a little easier to get started by using GraphQL's List type. Later, if you want to pagination/cursors, you can add Connection support (https://facebook.github.io/relay/docs/graphql-connections.ht...).
Is it possible to do more complex requests in GraphQL, like getting the favorite venues of people that favored "Garaje" or is it left to the API provider?
Not really. GraphQL mostly provides an alternative to REST when you want to select specific fields and traverse down into relationships with a single query.
The closest you could get is the users who rated the business:
business(id: "garaje-san-francisco") {
reviewers {
rating
user {
name
}
}
}
If Yelp wanted to enable that use case, they would add a field to Business like `related_businesses` like:
business(id: "garaje-san-francisco") {
related_businesses {
business {
name
}
}
}
I have been using GQL with a Play! in Scala. If anyone else is thinking about doing GQL in Scala I highly recommend using Sangria [0], its well documented and easy to work with.
Your question doesn't really make sense. You are specifying the data that you want back from the API. What gain would be using key:value syntax be in this situation? The request would just be littered with `"requested_data": true` which is just wasteful.
Well, you could do arrays of strings and objects instead of key:value pairs. Although I suppose there would be a lot of superfluous quotes, and part of the point is to optimize for mobile...
The API itself is a Python service running on Pyramid/uWSGI. Our focus on services internally means that the API delegates our REST requests to other internal services when resolving the data.
As far as the GraphQL implementation, we used Graphene (graphene-python.org) for that.
We're still working on documentation among other things before further publicizing it. Hope to take lessons from Yelp and others on best practices with it.