Introducing Yelp's GraphQL API
engineeringblog.yelp.com
engineeringblog.yelp.com
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.
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.
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
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.
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.
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/
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.
https://whosonfirst.mapzen.com/
(Disclaimer: I work for Mapzen)
Is there any information on challenges developers have found with GraphQL out there?
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'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...).
One very common failure mode we observe with GraphQL users: they do not have a clearly defined boundary between their GraphQL schema definition and their domain layer: http://graphql.org/learn/thinking-in-graphs/#business-logic-...
Try https://learngraphql.com gives a very good idea of what graphql is. Way better than reading the official documentation or spec.
Once I went through it, made up my mind that our API as a service product should support Graphql.
Note: I am in no way related to the site.. It is free and I finally actually understood what graphql is in 15 mins.
The closest you could get is the users who rated the business:
business(id: "garaje-san-francisco") {
reviewers {
rating
user {
name
}
}
}
business(id: "garaje-san-francisco") {
related_businesses {
business {
name
}
}
} business(id: "garaje-san-francisco") {
reviewers {
rating
user {
name
favorited_businesses {
id
name
}
}
}
}Using the business as the root query would be a bit cumbersome, but more like:
business(id: "garaje-san-francisco") {
reviewers {
user {
name
favorited_businesses
favorited_businesses(name: "garaje")
}
}
}
user {
name
favorited_businesses
favorited_businesses(name: "garaje")
}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.