
Introducing Yelp's GraphQL API - syrusakbary
https://engineeringblog.yelp.com/2017/05/introducing-yelps-local-graph.html
======
nowarninglabel
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](https://api.kivaws.org/graphql) with some
general API info at [https://build.kiva.org](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.

~~~
abuani
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.

~~~
atticusberg
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.

~~~
MrBuddyCasino
"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

~~~
neebz
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.

~~~
ruslan_talpa
If your database is PostgreSQL (which it should be :P) then
[https://subzero.cloud](https://subzero.cloud) might solve that for you. Each
GraphQL request is translated to a single database query.

~~~
neebz
We are using MySql :)

------
huangc10
Going to sign up for the beta program. BTW, if you're in the SF area,
definitely try Garaje. One of the best tacos and beers around.

~~~
packetized
Also try Garajito and (the somewhat unceremoniously named) G-Spot across from
Moscone on 3rd.

------
rburhum
Nooooooooooo! Don't choose my favorite Taco spot as your sample query. The
line is already too long.

~~~
dannyr
There's now Garajito though in case line at Garaje is long.

~~~
rburhum
No beer sold at Garajito just yet :(

------
taylorbuley
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/](http://www.mapcode.com/)

~~~
yellowbkpk
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.

[https://whosonfirst.mapzen.com/](https://whosonfirst.mapzen.com/)

(Disclaimer: I work for Mapzen)

~~~
taylorbuley
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!

------
Bahamut
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?

~~~
zehtomer
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.

------
developer12
Not sure if anyone at Yelp reads HN but looks like a bunch of the sample
queries are broken. I'm not familar enough with GraphQL on how to fix them.

[https://www.yelp.com/developers/graphql/query/reviews](https://www.yelp.com/developers/graphql/query/reviews)

~~~
clay_to_n
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?

~~~
developer12
Once you create an account you will also get an error about needing a
business_id. But using the pre-filled example or sample above it won't work.

------
ncrmro
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!

------
andysinclair
Another option for providing a queryable RESTful API interface is OData
[http://www.odata.org/](http://www.odata.org/)

~~~
skrebbel
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?

~~~
robzhu
> 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...](https://facebook.github.io/relay/docs/graphql-
connections.html)).

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-...](http://graphql.org/learn/thinking-in-graphs/#business-logic-layer)

------
aamederen
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?

~~~
searchfaster
Yes.. Its left to the API provider.

Try [https://learngraphql.com](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.

~~~
SmellTheGlove
Thanks for sharing that link, looks really good. I'll be going through it
after work.

------
tylerpachal
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.

[0] [http://sangria-graphql.org](http://sangria-graphql.org)

------
not_kurt_godel
Can someone explain why GraphQL was designed to be non-JSON? Seems like a
stupid decision, unless I'm missing something.

~~~
Sholmesy
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.

~~~
yen223
Equally important to note: the _result_ of a GraphQL query is valid JSON.

~~~
Sholmesy
Totally. Just assumed OP meant the request, as the responses are very clearly
valid JSON.

------
ram_sankar83
What language or tech stack has been used to implement this API?

~~~
zehtomer
As bpicolo said, lots of Python.

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.

------
batmansmk
Awesome!

