Hacker News new | past | comments | ask | show | jobs | submit login
Introducing Yelp's GraphQL API (yelp.com)
202 points by syrusakbary on May 3, 2017 | hide | past | favorite | 51 comments

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.


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

We are using MySql :)

I'd echo the comment down the line a bit for the pros / cons: https://news.ycombinator.com/item?id=14264977

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.

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.

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

And if you're a fan of poor life choices or post lunch naps, then their Zapatos are excellent!

These recommendations would have been great 6 months ago; unfortunately I just moved to San Antonio.. Actually, I'm flush for great tacos now :D

Amazing burgers also :) Love that place.

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

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

No beer sold at Garajito just yet :(

My thoughts exactly.

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.


(Disclaimer: I work for Mapzen)

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.

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.


Hey! I fixed reviews so the example should work now and pushed out a change to the developer site to fix a broken example I noticed.

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?

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.

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!

Another option for providing a queryable RESTful API interface is OData http://www.odata.org/

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

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

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?

Yes.. Its left to the API provider.

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.

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

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 {
      user {
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 {

You can recurse in GraphQL so if they added a `favorited_businesses` field to `user` then it would be possible. Something like this:

  business(id: "garaje-san-francisco") {
    reviewers {
      user {
        favorited_businesses {

GraphQL looks cool, kind of fancy but simpler way to do some complex SQL without the SQL.

Using the business as the root query would be a bit cumbersome, but more like:

   business(id: "garaje-san-francisco") {
      reviewers {

      user {



        favorited_businesses(name: "garaje")




If they provide user queries, then something like:

      user {



        favorited_businesses(name: "garaje")


Left to the API provider. The provider specifies arguments you can provide per field. You can call those arguments.

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

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

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.

Equally important to note: the result of a GraphQL query is valid JSON.

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

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

What would the values of the keys be?

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

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.

Yelp uses lots and lots of Python :)


Please don't take us off topic into this territory. We don't need every thread about Yelp to rehash the same discussion over and over again.


Applications are open for YC Winter 2022

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact