Adopting GraphQL in an Enterprise

Hello, everybody. Thank you for coming to my talk. Today, I'm going to be talking about adopting GraphQL in an enterprise. Before we get started in the talk, here's what we're going to talk about. We're going to talk about why GraphQL may be a good technology for an enterprise. Our story of adopting GraphQL in PayPal and the lessons we learned, the challenges we had, some best practices we adopted, and if you are interested in getting started with GraphQL, how you can get started.

Before I get started with my talk, I would introduce myself. My name is Shruti Kapoor. I'm a senior software engineer at PayPal. You can find me on Twitter at Shruti Kapoor08 or you can find me on Twitch at twitch.tv slash Shruti Kapoor where I share live streaming sessions of me working on something like a presentation like this. So I invite you to come and work on your side projects with me.

When we started adopting GraphQL at PayPal, when I first started PayPal I had actually never worked on GraphQL before. I kind of thought like GraphQL was like this technology that was used to fetch data, but I thought it was connected somehow to Facebook so I had no idea how to work with GraphQL. I thought it was related to GraphCMS and that was the extent of my knowledge. So when I got started at PayPal, my role in the team was to work on an internal project which was a brand new project and we were supposed to consume almost five internal APIs. These are all REST APIs. Our front-end application was supposed to be a NodeJS app, but what we used in the frontend of that NodeJS app was up to us and so we decided to use GraphQL as the frontend layer of that NodeJS app.

Why we decided to use GraphQL, I'll get into in a bit, but when I first got started into GraphQL at PayPal, there weren't a lot of people or a lot of teams that were using GraphQL. The main team that was using GraphQL was the Checkout app, which you may have seen when you check out at PayPal. That was actually the trailblazer of adoption of GraphQL at PayPal. They advocated GraphQL and the benefits of adopting GraphQL within PayPal and inspired the rest of the company to start adopting GraphQL. At the time, in 2018, we didn't have a lot of central support. Initially, teams were slowly starting to pick up GraphQL, but it was kind of very independent and dependent on the team itself to adopt GraphQL and kind of overcome challenges. Even the community was pretty early stages, but since then, a lot has changed outside in the community and at PayPal itself. Within PayPal, in the last three years, there's now 50 apps that use GraphQL in production. We do have a GraphQL public API as well that is powered by BrainTree. And in our internal Slack community, we have almost 500 members. So all of that is to say that GraphQL is picking up a lot in PayPal and we're heavily using GraphQL at PayPal. We have built internal tools to support GraphQL, especially the libraries that we had at PayPal. Now we provide infrastructure support and we provide training to adopt GraphQL for teams that are now adopting GraphQL, especially giving them some sample frontend apps and some sample backend apps to get them started easily on GraphQL.

And for any frontend application that's building a UI, GraphQL has now become a default pattern for adopting, for putting it as the frontend layer of UI. Our reasons to adopt GraphQL at the time could be explained by understanding what our challenges at the time were. So when we were thinking of adopting a new technology or when we were thinking of a solution actually, these were some of the problems that we had at the time.

Our number one problem was that because, and this is specifically in regards to our company being a heavily REST, heavily REST API powered company, so we did have a lot of REST APIs and our frontend application that we were working on was supposed to talk to five different REST APIs. What ended up happening was that our UI may need like one field, but to get that one field, we would have to call a REST endpoint and the REST endpoint may be servicing a bunch of different UI applications as well. And so what ended up happening was we would call the REST API and we would get lots of overfetched data and that data would have to throw away on the client side and only use that one field. So one of the problems, one of the biggest problems we were facing at the time was we were fetching too much data from REST APIs and not using all of it.

And because we had so many different REST APIs, we also had to figure out which API to call to get the information we needed. And what that often involved was we first have to get authenticated from an API, then we'd have to use that token to call another API, maybe we get the user's ID from that information, from that API, and then we'd use that ID to maybe call their profile API and get their name and such and maybe their balance and such information. So basically what ended up happening was we'd call multiple round trips, use one field from one API and send it over to another API. And so that led to a lot of frustration because we were calling so many different APIs on our front-end applications.

Also because we were heavily versioned APIs, what ended up happening was that we would release a new version and if we had to update a field or if we had to rename a field, anybody who would be integrated with the previous version would now become outdated. And it was becoming really hard for us to deliver updates to these clients. It wasn't always feasible for clients to upgrade to our latest versions. So what ended up happening was most of our clients started staying on the older version while we were publishing newer versions of the API. Another problem was because we had REST APIs all across the board, what may have happened is that one field was called something else in one API like username, but something else in the other API like user or name. And so the integration experience itself was also very inconsistent. So as a frontend developer, we had to figure out what maybe do some formatting on the client end side, even to call the API itself and format our data before we send it to the server side. So the integration experience itself was quite inconsistent. So the right candidate that we were looking, would provide us the ability to have a uniform experience for all of the APIs that we were about to fetch across the board. And another important thing was the ease of integration across the board. So we wanted to make sure that the API, that the technology we would use, would not require a client, especially our sister companies, to have any prior information about our APIs itself. So for example, if our sister company like Braintree had to integrate with PayPal, we didn't want Braintree to know the ins and outs of calling a REST API, or calling an API on PayPal's side. We wanted them to have an easy interface that they could just integrate with, something that they'd be familiar with, without having to worry about what goes behind the scenes. Another thing that we wanted was because we were pushing out updates and we wanted to deprecate fields intelligently, we wanted to make sure that we have detailed analytics on which field was being used from the graph QL endpoints, or from our REST endpoints, or from our API endpoints. So we wanted to make sure that if we are pushing out updates, we are doing them intelligently and we have instrumentation behind those. Another thing that we noticed that was happening in our teams was our frontend and backend developers often would have this conversation. So the frontend developers would say like, we need to add more data. And one of the questions that was asked is, should we get version APIs? But the problem with version API is that if you do introduce breaking changes, then what is the best practice of introducing a breaking change? And if you go from V1 to V2, what happens to all of the clients that are not integrated with V2 yet? They do not get the updates yet. So what is the best solution there? Another alternative is if you need to ask more data.

If you need to ask for more data, the use case that we used to discuss was, if you do need to ask for more data, should we add a new endpoint? So if you already have users should we add like username? Adding a new endpoint always is not a favorable approach, so usually an alternative that can be used is adding maybe query parameters. But one or two query parameters is okay, but as we start asking for more and more data, the query parameters also start getting polluted, so that's not always an ideal approach as well.

The other approach is to add it to an existing endpoint and ask for more data in the existing endpoint, but that breaks integration of people, especially if it's a required field that breaks integration of people who are already integrated. And so those are some of the common challenges we were facing when we were looking for an alternative technology. And so that's where we thought that GraphQL could really help us, because one of the biggest problems was that we were versioned, and with the help of GraphQL, we have one endpoint and we have no more versioned APIs. So that meant that all of our integration experience was at one place, and it was all uniform. But also when we do update, when we do deliver updates, it would be delivered to the client as soon as they push it out, and those who want to integrate with the new data can integrate at their own time. And it was really awesome for us to see the detailed analytics that was coming from these fields, and it became much easier for us to add a new field or to mark fields as deprecated to let clients know that these fields would be going away, and so we could intelligently deprecate fields without having to blindly remove them and perhaps break somebody's integration experience. Another cool thing that comes with GraphQL is because you only ask for the data that you need, that also led to smaller payloads and also less wastage of data on the front end side.

As a developer, when we showed GraphQL to our folks, to our developer teams, they were really excited, especially by looking at the developer tooling that exists in the community even right now and back in the day in 2018. Especially when we showed people GraphQL, everybody was so happy to see the explorability of docs and the fact that you can fire a GraphQL query right away. Another cool thing that happened with the introduction of GraphQL was our front end and backend teams started collaborating a lot more, because you have to establish schema in the beginning itself. That meant that you have to set up that contract between the front end and backend teams, and so that increased the collaboration between our teams, which is a great side effect of adopting GraphQL. An awesome thing about having a schema is also that because it's a contract, that means that your front end team can look at that contract and develop their front-end application, while the backend team can look at that contract and develop the backend side, the GraphQL API side. That means that once the schema is established, it helps teams to ... While the schema is being established, it helps to bring teams closer. But once the schema is established, it also helps to let the teams work independently, which we thought was super cool.

There are a few different approaches of adopting GraphQL, and we considered a few different ones. Here's some of them. I think the most popular one is adopting GraphQL as kind of like an orchestration layer or a wrapper over a REST API. It kind of looks something like this. Let's say that you have a UI application that's calling a bunch of different REST APIs, it's calling three different APIs. A very common technique is to introduce GraphQL as kind of like an orchestration layer or like a facade between your frontend layer and your backend layer. Where you put your business logic really depends on your application, but a lot of folks would put their business logic, their heavy business logic in the REST API, so like calling the database, things like that, or deciding which business use case that is in the REST APIs itself, like wherever that exists right now, but they'll put the lighter business logic in GraphQL APIs. So it really depends on your application, but basically the business logic can live either in the GraphQL layer or in the REST API layer like how it does right now. Another technique for those clients who are really tied down to REST is that you can introduce REST wrapper over GraphQL APIs. So this way you can still get the benefits of GraphQL API as an orchestration layer, but this also gives you an added advantage that if you have clients that you know would not be migrating over to GraphQL, you can still surface a REST API for them. Another thing is that if you do have applications that perhaps are on a legacy system, and you do not want to touch them, you can also have GraphQL and REST co-exist together. So it kind of looks something like this. So let's say that you have one route that talks to GraphQL, and then you have another route that talks to REST API.

So your GraphQL APIs and REST API kind of exist together. REST API is just your legacy system, and then GraphQL API is where you build all of your new technologies, your new business logic. So they both kind of live together.

For us, while we were adopting GraphQL, we had a few different options of plugging in GraphQL, and here are some of them. So we thought that we could start by converting our existing APIs into GraphQL and maybe do it one step at a time, one endpoint at a time. Another approach we thought was perhaps we could convert everything new that we're building into GraphQL APIs, and so we'd build these as standalone APIs, and this was especially useful for applications that are going to be powering UI front-end, like UI layers.

A few things that we had in mind before plugging in GraphQL was, when we were choosing an application, was who especially is the client that is going to be using the API, and if they would be open to calling GraphQL. So for example, if it was an external client or a customer, and we knew that they would not be open to calling GraphQL, perhaps we would introduce GraphQL in a different place. But if it was a front-end application, and front-end application would be open to calling GraphQL, then that would be a really good candidate of introducing a GraphQL API. Another thing was, how many downstream APIs are we calling, and this is especially useful because we were talking about getting smaller payloads, having a consistent experience, and detail analytics, so if we have multiple different APIs we're going to be calling, then it would be a really good candidate of calling, of creating a GraphQL layer. But if there is only one REST API we're going to be calling, it's not really a good application of GraphQL because then we'll be duplicating all of the work that's happening in the REST layer and making double the amount of effort. Another thing we had in mind was also what is the business impact and and the business side of application basically, so who does this business, who does this application serve, who are the stakeholders, what is the time frame, how long can we take to convert this app into a GraphQL layer or into a GraphQL app? So we thought that we'd first start with like a first application and kind of convert a first kind of like this demo application to a GraphQL application and so we started with the tool that I was working on, it was actually a new internal tool that we were building, our stakeholders were internal customers, internal teams actually, customer service reps, the, we were calling five different downstream APIs and the front-end application which was my team was super open to being integrated with GraphQL so it became a really good candidate for experimenting with GraphQL.

Our goal for this app was to make it fast and make it lightweight and basically that meant that we shouldn't send any extraneous data, so GraphQL was a really good candidate there and we didn't want to add any libraries that we didn't need, any third-party libraries that we didn't need and so what ended up happening was when we introduced GraphQL we noticed that we don't really need a lot of state management so we were able to get rid of Redux and we just use React State with the help of Apollo Cache to get rid of our state management solutions. So basically we ended up, with the help of GraphQL, we ended up shipping less data and we ended up using less libraries. And so for that business logic we were the team who owned one of the backend REST APIs so we ended up putting all of our heavy business logic in our backend REST API itself. We had our orchestration layer of GraphQL as kind of like a simple, like a proxy layer, between a front end, between our front end application and our business logic layer which was the REST API. For authentication we used existing REST APIs that exist in Paypal itself, so it was our existing infrastructure, and then the rest of the downstream REST APIs we kept it in the API itself, we did not touch any of that. So basically our GraphQL orchestration layer was a simple, thin orchestration layer, it kind of, it was really cool to see because you were still able to use all of the benefits of GraphQL and we found that GraphQL really works really well as an orchestration layer.

And so our architecture kind of looked like this. So we had the GraphQL layer that was the first layer that the UI would talk to, and that was the only layer that the UI would talk to. And then the GraphQL layer will kind of do the job of like figuring out when to call the authentication layer, when to call analytics, when to call REST API. So GraphQL kind of did this job of like acting as a facade between all of the different REST APIs we had in our application that the application was supposed to talk to. So basically what we ended up learning for our first application, that is that it's really cool to wrap a REST API with the GraphQL API and kind of work, kind of create our GraphQL layer as an orchestration layer. And the client is still able to use the benefits of GraphQL, even though we don't have to change anything that's downstream. And that was really awesome to see. And another thing was that because we also own the backend REST API, our backend developers didn't have to change the way that they were working. So it was really cool because they were independent and the way that they wanted to work, which was awesome. And it brought our front end and backend developers really close because we established a schema and we had a contract to go from. Everybody was talking to everybody and everybody was super happy because we had team collaboration. So we ended up creating GraphQL interface to orchestrate that new REST API, and we were able to deliver only the data that we need and make it easier to evolve the REST API over time.

Another approach of adopting GraphQL and looking at another type of application is something like this, where you put all of the business logic in the GraphQL layer itself. So the GraphQL layer is the main layer that you build on, so that's where you put all of the business logic, and the GraphQL layer will do the job of calling whichever REST APIs it needs to. But here you're not working on any REST APIs, you're working on only the GraphQL layer. So everything goes within the GraphQL layer.

The current status of GraphQL adoption in PayPal is that most of our applications are now defaulting to GraphQLs, especially if it is a front-end application, especially if it's an app that needs to power a UI layer. They're all defaulting to adopting a, they're all defaulting to using a GraphQL layer as the first facade, as the first layer. We are starting to get our material applications to move to GraphQL as well, which is really cool to see. Our back-end teams are still a little bit hesitant, especially the ones that are sitting very close to the database. And that's okay. They are still on REST APIs and that's okay. So we have a good mix of REST APIs as well. We do have most of our applications running independently on GraphQL. So we have a bunch of different GraphQL endpoints in the company, but we are trying to move towards like a federated one graph unified graph approach. So we are on our way there. Well, we're not there yet.

So I think one thing that helped a lot in convincing folks was the dev productivity. So we noticed that GraphQL was whenever we showed GraphQL to our folks, people would be really excited to see GraphQL. It was really cool, especially because we had so many different APIs across the board, and to have all of that at one place and being able to go from one documentation to another and being able to file whichever query we wanted to, that was really awesome. I think that's where we saw the most benefits of adopting GraphQL. Another really cool thing was because we knew what fields are being used and how often they are being used, it was really cool for us to see instrumentation behind it because we knew how slow a field would be, how slow a mutation would be, or a query would be. It was really cool to see because we had granular level of control over our APIs and granular level of knowledge of our APIs. And it was really cool for us to evolve to GraphQL over time because once we established a Schema contract, our API developers could work independently and we didn't have to hold back one team from another. And our UI was the one that was now driving the schema. So no longer did we build APIs blindly hoping that these fields would be used, but instead we had a UI that would drive which field would get inserted into the schema and that would be the field that would get developed. So this way we were intelligently building our APIs. Another cool thing of adopting GraphQL is the performance that comes with it and performance in the sense that because we're shipping less data the clients have to do less work of throwing away or clients don't have to do the work of throwing away data. So that means already we're sending smaller payloads, but also because we do not have to format the data anymore because the data is in the format that the client asked for, we do not have to write a lot of third-party libraries, incorporate a lot of third-party libraries or develop logic on the front end layer to format the data in the shape that we need it. So after adopting GraphQL, here's some of the lessons that we learned. The first lesson is to pick a first app and that really helps because that app can kind of serve as an app that can teach you lessons on adoption of GraphQL within your own company. So start with an app that has a low business impact and the stakeholders are your internal teams and orchestrate your REST APIs into GraphQL APIs because then you don't have to boil the ocean and convert everything.

Don't do a one-to-one mapping of REST to GraphQL because then you're just wasting your resources on basically duplicating work and you're not getting the benefits of GraphQL if you're doing a one-to-one mapping of REST. Well, all the benefits of GraphQL if you're doing a one-to-one mapping of REST.

Another really cool thing of building GraphQL that we saw in our team was that it brought our teams together. So build schemas together with front-end and back-end teams and use the built-in GraphQL features. For example, type safety or directives and those help a lot, especially things like Deprecator. We use them all the time. But I do have to give a word of caution, which is that a lot of folks think that adopting GraphQL would make the application really fast. But it's not true. GraphQL would still be only as fast as your slowest endpoint. There is a little bit of performance boost that comes with GraphQL because you'll be shipping less data and you'll be asking for less data. But if one of your REST APIs is really slow, that's the first thing that you'll need to fix instead of adopting it, instead of putting a GraphQL layer on it, because you won't see much benefits otherwise.

Another thing is that if you are an application that does not know what the schema would be in advance, it's kind of hard to build that schema because the schema has to be built in advance, you'll need to establish a contract in the beginning. So you'll have to think about what your fields need to be named, what queries and mutations you want to power. So if you are an application that does not know that, think about where the GraphQL is a good fit for you. So overall, I think there still are challenges of GraphQL in the community itself. For example, caching and error mapping are still being developed. You do need to know the schema upfront and making one graph sometimes is really hard, especially we're seeing that in our company, especially when we have different repos. There are some challenges of GraphQL. Think about where the GraphQL would still be a good fit for you.

Now, if you do think that GraphQL would be a good fit for you, here are some next steps that you can do. Do a similar exercise in your team and assess if GraphQL is the right fit for your architecture in your enterprise. Some of the questions you can ask yourself is what are some challenges that your teams are facing and who are your stakeholders and client developers? Who would have the ownership of the GraphQL layers and the REST APIs? And where do you want to put your business logic? Would it live in the GraphQL layers or would it live in the existing APIs that you have? Another thing that you need to think about is what specific company infrastructure that you need to adopt. So for example, you may have authorization, you may have experimentation, analytics, monitoring. Where are you going to put all of that in your GraphQL architecture? Another thing like I was saying is, would you be saving any data by converting to GraphQL? Especially if you need to use everything that your REST API gives you in your GraphQL layer? Would you be saving any data by converting to GraphQL in that case? And if you do depend on heavily on caching, error mapping and handling, how are you going to solve those problems with GraphQL? Another thing is when you're scaling GraphQL within your company is how will you onboard new teams? And you'll need to set up a team that is going to enforce standards like naming GraphQL API's mutations. And how would you deal with changing schema? So if you do need to rename fields in your schema, how would you do that? So overall, I think if you want to get ready about on adopting GraphQL, here's an exercise you can do. You can do a dog food exercise with your company and try converting one of your applications to a GraphQL application and note down all of the challenges that you face. Set a standards team that will help you solve those problems within your company itself. So for example, like schema unification, especially if you are a company that has microservices across the team and you want to convert one API at a time. Set a standard scheme that will help you solve those problems together. And explore what open source libraries you can use.

The power of GraphQL is the community that powers it. So think about like what open source libraries you can use and determine how you're going to adapt, how you're going to scale GraphQL within your own company and how you're going to enable other teams to adopt GraphQL.

So basically if you want to sell GraphQL to your team, I have a few tips to focus on, focus on their productivity and focus on the fact that you can incrementally adopt GraphQL and you don't have to convert everything into GraphQL at the same time, focus on the fact that it increases collaboration between frontend and backend teams and the fact that there is a lot of tooling in the community, open source tooling in the community that you can leverage. There are no versions so everybody will get the same updates and the same deprecations. And the fact that it's similar to JSON means it's easier for folks to understand who are already working with JSON data.

And if you want to talk GraphQL, here's my recommendation of putting GraphQL in your app. I think you can use GraphQL as a kind of like an orchestration layer between your current layers, your current business logic, your current infrastructure, and your UI layer. So UI could only talk to the GraphQL layer and that's all the UI has to worry about. The GraphQL layer will do the job of figuring out which API to call. All of your business logic, anything heavy that you currently have, that can stay in the REST API layer. But anything lighter weight can stay in your GraphQL layers. So this way, you'll be able to adopt GraphQL, kind of like insert GraphQL easily within your application without having to change too much of what you have right now. So basically, start with a small app, convert one API at a time, and establish teams that will help you adopt GraphQL within the company itself.

Now to wrap up, I would like to say that no technology is perfect. GraphQL does have its benefits, but it does have its challenges as well. So assess for the GraphQL would be a good fit for you before you adopt GraphQL. But I would like to say that GraphQL is here to stay, and it is a really good time to get started with GraphQL, especially in an enterprise. The power of GraphQL comes from the community. So get involved in the community, and use the open source libraries that are out there. We have written a blog post on a success story of the Trailblazer app, which is a PayPal checkout, and Max Stewart wrote this article. So here's the link for that article if you're interested in the technical decisions we made, especially for the Trailblazer app. Here's a few different articles that are really cool. Expedias article is really cool. And Mark Andre's book on production-ready GraphQL is awesome, if you want to adopt GraphQL within your enterprise. That's all I have for you. Again, you can reach out to me on Twitter at shruthigapoor08 if you have any questions, or you can reach out to me on Twitch. I will also send a snippet of this in my newsletter at hindlinader.com if you're interested in a summary. You can find all the slides here. And you'll find a snippet here. Before I leave, I want to leave with one final dev joke.