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 with 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 ShrutiKapoor08, or you can find me on Twitch at twitch.tv slash ShrutiKapoor, 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 I started adopting GraphQL at PayPal, when I first started PayPal, I had actually never worked on GraphQL before. I thought 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 were all REST APIs. Our front-end application was supposed to be a Node.js app, but what we use in the front-end of that Node.js app was up to us, and so we decided to use GraphQL layer as the front-end layer of that Node.js 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 a checkout app, which you may have seen when you check out with PayPal. That was actually the trailblazer of adoption of GraphQL at PayPal, and 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 very independent and dependent on the team itself to adopt GraphQL and 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. In our internal Slack community, we have almost 500 members. 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 front-end apps and some sample back-end apps to get them started easily on GraphQL. For any front-end application that's building a UI, GraphQL has now become a default pattern for putting it as the front-end layer of UI. Our reasons to adopt GraphQL at the time could be explained by understanding what our challenges at the time were. 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 API-powered company, so we did have a lot of REST APIs. Our front-end 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 one field, but to get that one field, we would have to call a REST endpoint, and the REST endpoint may be surfacing a bunch of different UI applications as well. What ended up happening was we would call the REST API and we would get lots of overfetched data, and that data we would have to throw away on the client-side and only use that one field. 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. 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'd 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 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. 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. That lead 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 when we'd release a new version, and if you had to update a field or if you had to rename a field, anybody who would be integrated with the previous version would now become outdated. 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 another API, like user or name. The integration experience itself was also very inconsistent. As a front-end developer, we had to figure out what the 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. The integration experience itself was quite inconsistent. 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. Another important thing was the ease of integration across the board. We wanted to make sure that the technology we would use would not require a client, especially our sister companies, to have any prior information about our APIs itself. 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 side. We wanted them to have an easy interface that they could just integrate with, something that they'll 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 GraphQL endpoints or from our REST endpoints or from our API endpoints. 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 front-end and back-end developers often would have this conversation. The front-end developers would say, like we need to add more data. 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? 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 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 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. Another 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. So those are some of the common challenges we were facing when we were looking for an alternative technology. So that's where we thought that GraphQL could really help us, because one of the biggest problems was that we were versioned. 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 deliver updates, it would be delivered to the client as soon as they push it out. Those who want to integrate with the new data can integrate at their own time. 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. 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 back-end 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 back-end 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 back-end team can look at that contract and develop the back-end 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 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 an orchestration layer or a wrapper over a REST API. It looks something like this. Let's say that you have a UI application that's calling a bunch of different REST APIs, so it's calling three different APIs. Very common technique is to introduce GraphQL as an orchestration layer or a facade between your front-end layer and your back-end layer. Now, 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 calling the database, things like that, or deciding which business use case that is in the REST APIs itself, whatever that exists right now, but they'll put the lighter business logic in GraphQL APIs. It really depends on your application, but basically the business logic can live either in the GraphQL layers or in the REST API layers 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. 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 application 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 looks something like this. Let's say that you have one route that talks to GraphQL and then you have another route that talks to REST API. Your GraphQL APIs and REST APIs 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 live together. For us, while we were adopting GraphQL, we had thought of a few different options of plugging in GraphQL, and here are some of them. 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. The 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. This was especially useful for applications that are going to be powering UI layers. A few things that we had in mind before plugging in GraphQL was, when you 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. 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. This is especially useful because we were talking about getting smaller payloads, having a consistent experience, and detail analytics. If we have multiple different APIs we're going to be calling, then it would be a really good candidate 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 the business side of application basically. So 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 would first start with a first application and convert a first 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. 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 used React State with the help of Apollo Cache to get rid of our state management solution. 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 back-end REST APIs. So we ended up putting all of our heavy business logic in our back-end REST APIs itself. We had our orchestration layer of GraphQL as kind of like a simple, like a proxy layer 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 was really cool to see because we were still able to use all of the benefits of GraphQL, and we found that GraphQL 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 would kind of do the job of figuring out when to call the authentication layer, when to call analytics, when to call REST APIs. So GraphQL kind of did this job of 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 a GraphQL API and kind of create that 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 in the way that they wanted to work, which was awesome. And it brought our frontend and backend developers really close because we established a schema in the beginning 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 where you'll put any... So the GraphQL layer is the main layer that you build on. So that's where you'll 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 frontend application, especially if it's an app that needs to power a UI layer. 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 backend 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, but 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 kind of 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're 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. So it was really cool to see because we had a 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 in the schema. And that would be the field that would get developed. So this way, we're 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 needed. 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 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, 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 need to establish the 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 whether GraphQL is a good fit for you. So overall, I think there still are challenges of GraphQL in the community itself. Like 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. So there are some challenges of GraphQL. So think about whether GraphQL would 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 think you should be? Who would be the stakeholders in your team? Who would be the stakeholders in your team? And where do you think you should be? And where do you think you should be in your team? So think about that. So what are the challenges that you're facing? What are the challenges that you're facing? And where do you want to put your business logic? Whether it's, would it live in the GraphQL layers, or would it live in the existing APIs that you have? Another thing that you can, you need to think about is what specific company infrastructure that you need to adopt. So if you're a company that's doing a lot of work and you're doing a lot of work on your team, how are you going to 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, like would you be saving any data by converting to GraphQL in that case? And if you do depend 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? APIs, 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 kind of 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. So set a standards team that will kind of 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 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 front end and back end 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 adopt 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. And 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 the checkout on a success story of the Trailblazer app, which is a PayPal checkout and Mark Stewart wrote this article. So here's the link for that article if you're interested in the decisions we made, the technical decisions we made, especially for the Trailblazer app. Here's a few different articles that are really cool. Expedia's article is really cool. And Mark Andre's book on production-ready GraphQL is awesome on 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 shruthikapoor08 if you have any questions or you can reach out to me on Twitch. I'll also send a snippet of this in my newsletter at tinyletter.com slash shruthikapoor if you're interested in kind of like a summary. You can find all of the slides here and you'll find a snippet here. Before I leave, I want to leave with one final Dev joke. Thank you so much, everybody.