WEBVTT 00:00.000 --> 00:27.640 I'm going to talk a little bit about two very popular API technologies and try to bridge 00:28.280 --> 00:39.400 what's the name of my name is Martin. I love bikes and bananas and I do love GraphQL so small 00:39.400 --> 00:47.480 disclaimer here I'm pretty new to the Open API world but this is an exercise like what's 00:47.480 --> 00:53.640 happening when someone that does a lot of GraphQL tries to look into Open API so hopefully 00:53.720 --> 01:00.440 that can bring some interesting discussions and if I'm saying something stupid please let me know. 01:02.040 --> 01:07.640 I'm working at Apollo on this project called Apollo Kotlin which is a GraphQL client for Kotlin. 01:10.280 --> 01:15.880 What Apollo Kotlin is doing is it takes a GraphQL schema, it takes an operation, so query, 01:16.840 --> 01:24.120 process everything all together and generate Kotlin so Kotlin is a I level general proposed language 01:25.240 --> 01:32.440 mostly use Android but you can use it everywhere like iOS back end, lots of places 01:34.200 --> 01:39.400 and it's all type safe so you have your GraphQL server and you can be guaranteed that 01:39.400 --> 01:46.360 your query is going to run all the way from your back end to your front end without any bugs at 01:46.360 --> 01:54.360 least in theory. It's a very low level library so in order to showcase it and to showcase like to 01:54.360 --> 02:03.080 make people use more GraphQL my web colleagues did this cool stuff it's demo using the Spotify API 02:03.640 --> 02:09.960 so it showcases all the Apollo products and GraphQL in general like federation, router and all these 02:09.960 --> 02:17.080 kind of fun stuff and it uses Spotify which is something that we all know we all know what the 02:17.080 --> 02:25.400 playlist is we all know what the track is so it's a cool model to use and Spotify has a very cool 02:25.400 --> 02:34.360 rest API it's very well documented and it even has an open API schema on the right here following 02:34.360 --> 02:42.600 the previous presentation I run it in right my API and it's good it's a good rest API 02:43.880 --> 02:52.440 now any problem is it's not a GraphQL API and for my for my needs I need a GraphQL API so I was like 02:52.440 --> 03:00.440 what if I could take this open API schema process it automatically, turn it into a GraphQL schema 03:00.440 --> 03:07.400 and API and then do the same thing with Apollo Kotlin because at the end I want to have fun with 03:07.400 --> 03:15.880 Apollo Kotlin and so I would have a full end-to-end like from rest to GraphQL to my clients my 03:15.880 --> 03:25.640 Android app so this is like again it's very small but we are going to look at some portion one after 03:25.640 --> 03:34.280 the others. Lorna talked about it I hope you know about open API it can come in boss 03:34.840 --> 03:43.960 Yamal and Gison like this is a Yamal version and what I'm suggesting is that we take this like open API schema 03:44.120 --> 03:49.160 and we turn it into a GraphQL API so that's our goal for today. 03:52.680 --> 03:58.280 If we take the first line this is info that Lorna was talking about earlier today 03:59.240 --> 04:04.040 that tells a bunch of information about your schema like the open API version 04:05.080 --> 04:13.400 the version of the Spotify API itself one dot zero dot zero by the way it's not using the latest version of the 04:13.480 --> 04:21.560 spec so if someone works at Spotify here probably time to update I guess there's a title and a 04:21.560 --> 04:27.080 bunch of URLs here there is only one but this is where you can make your API calls. 04:28.520 --> 04:36.200 Well in GraphQL it's a lot more easier because we don't have such melalata like the wall spec 04:36.280 --> 04:40.200 isn't really version it's always backward compatible and 04:42.280 --> 04:48.760 feature discovery is another story but you can get most of the feature discovery using something called 04:48.760 --> 04:56.840 introspection where you go to your URL and you get the schema author it's a new version for the 04:56.920 --> 05:07.880 schema for the Spotify schema either because like GraphQL uses more fluid philosophy of using 05:07.880 --> 05:15.560 deprecations or if a field well you evolve your schema through deprecation you first deprecate a field 05:15.560 --> 05:20.680 and once it's not used anymore you remove it and you add new fields when you need new features. 05:21.640 --> 05:32.200 Well else no URL in GraphQL because you have one single URL it's your main GraphQL URL it's your main 05:32.200 --> 05:38.040 endpoint and this is where you also get your schema from so it would be a bit redundant to add it 05:38.040 --> 05:45.400 also in the schema like it would duplicate information so in GraphQL you have this schema and a 05:45.400 --> 05:53.480 root query type where we are going to add some stuff. Now the interesting stuff like how you get your 05:53.480 --> 06:01.240 data in open API you have a list of paths which are really roots where you get your info your data from 06:02.600 --> 06:09.880 this is an example of using a playlist if you want to get a playlist so if I go there 06:10.280 --> 06:19.640 it's a get operation the schema author was very nice to include an operation ID this is going to be 06:19.640 --> 06:28.680 important we'll see that in two minutes and you have parameters ID it's in the past and 06:29.560 --> 06:38.360 it's completely types of the string here and you get back a response which is jason and which contains 06:38.360 --> 06:46.920 a composite object type containing a playlist so fast a good so the way you would do this in GraphQL 06:46.920 --> 06:54.600 is you would take every pass and you can turn this into what we call a root field so in that case 06:55.880 --> 07:03.640 I took my root query object here and I have a root field called get playlist here this is where 07:03.800 --> 07:10.280 operation ID is important because if I didn't have that I wouldn't really be able to find a good 07:10.280 --> 07:18.040 name for my root field I would have to guess from the pass or like I don't do some machine learning 07:18.040 --> 07:28.120 whatnot but the operation ID gives me something user friendly there input parameters same thing I have 07:28.120 --> 07:35.080 strings so the type system is really really similar it's really easy to map from a jason schema 07:35.080 --> 07:45.160 and open API types to the GraphQL ones and it returns a get playlist object which is a game 07:47.080 --> 07:52.280 I don't have a good name for it so I decided to is that something stupid on the slide? 07:52.280 --> 07:56.760 No, not a good. You tell me if I say something stupid I would open API. 08:02.360 --> 08:08.920 So for the output type it's yeah I reuse the same name as the field here because I don't have anything else 08:08.920 --> 08:16.440 so it's a gate playlist so it returns a get playlist why not and then we are going to put some more 08:16.440 --> 08:22.760 fields inside so if we go inside the playlist object we have a bunch of properties 08:23.880 --> 08:29.000 same thing by the way I did not mention but even the descriptions map really well like here you 08:29.000 --> 08:36.520 have an open API description and you have the same thing in GraphQL on the right so it allows you to 08:36.520 --> 08:40.840 generate documentation very easily and have the same documentation in both worlds 08:40.920 --> 08:50.440 well that's it's really easy for simple scala fields you can have a raise so if you have a 08:50.440 --> 08:57.000 list of tracks in your playlist here with a bunch of items which are tracks in GraphQL this is 08:57.000 --> 09:06.040 done using list so we use this square brackets here so the list and same thing here always naming 09:07.000 --> 09:12.680 complicated right like in software engineering it's always the same problems so for naming 09:12.680 --> 09:20.760 my object my composite object I used get playlist track so using the enclosing object and then the 09:20.760 --> 09:32.760 field so that it we have our nice schema we can take things even a little bit further because both 09:33.240 --> 09:41.480 GraphQL and open API support no liability so if you had information about no liability in your 09:41.480 --> 09:50.760 open API schema it will be included in your GraphQL schema so in the left you can see you have two 09:50.760 --> 09:59.160 keywords actually you have a required and a new level for the most part GraphQL doesn't really have 09:59.240 --> 10:06.600 a concept of required field like all the output fields are required so if you are schema designer 10:06.600 --> 10:14.760 doing open API I recommend you always mark all your fields required which I didn't do but 10:14.760 --> 10:19.880 I still always send the field so I just went ahead and assumed that we're always there 10:19.880 --> 10:30.280 that's it there's one thing that is still a little bit strange is that you know I still have 10:30.280 --> 10:38.840 this get playlist and get playlist track like my track object is still nested into very deep into my 10:39.560 --> 10:46.520 my root pass my root endpoint and this is weird right if I want to reuse my track somewhere else 10:46.520 --> 10:54.200 like just getting a track how do I do that and in open API there's a cluster which is called 10:54.200 --> 11:00.120 components which allow you to do exactly that so you can do it with responses with parameters 11:00.680 --> 11:09.320 with schemas so composite types yeah there's two version of schema like you have the 11:09.320 --> 11:16.200 gizzen schema and the main big schema but I will talk about composite types easier and so if I take 11:16.200 --> 11:26.360 back my schema here I can just flatten it by using component so beware group now it's flatten yeah 11:26.920 --> 11:33.720 it's a bit small but what's that doing it it's basically referencing right basically 11:33.720 --> 11:41.000 or reference it uses this dollar ref syntax and now I can use this name and it also gives me 11:41.560 --> 11:47.720 also good names because these names here there are defined manually so there are manually picked 11:47.720 --> 11:53.960 so they make a lot more sense than something that would have to be machine interpreted a machine 11:54.280 --> 12:03.880 generated anyway so we're all good oh I forgot that once we have components we can use we can 12:03.880 --> 12:12.920 do cool stuff with reusable components like polymorphism in GraphQL you have interfaces in open API 12:12.920 --> 12:20.840 you can do that with all of because if a if a no-brake has all the fields of another one it's 12:21.000 --> 12:28.680 exactly like inheritance so here I have an album simplified album object which 12:29.480 --> 12:39.560 depends on album based and it does not depend in open API world but it takes all the same 12:39.560 --> 12:48.200 fields so technically it's it's all almost like an interface and in GraphQL you would do it 12:48.200 --> 12:58.680 like this so you use this implements keyword and the same for unions GraphQL I use as unions 12:58.680 --> 13:06.760 and this maps really well to one of I'm not mentioning any of here because that doesn't 13:06.760 --> 13:13.480 map really well to GraphQL if you use any of like it it becomes it generates a lot of types 13:13.480 --> 13:22.520 because we have to make all the combinations for all the different possible values so looks like 13:22.520 --> 13:30.440 we're good we took our initial rest open API schema and we have a matching GraphQL schema 13:31.000 --> 13:38.920 completely typesage with the description all good but if you're doing GraphQL like there's 13:38.920 --> 13:47.800 something that is first a bit weird there is that in GraphQL really and it's in the name it's a query 13:47.800 --> 13:52.680 language and so when you have something like this at the end of the day like the name of my 13:52.680 --> 14:00.040 object still has playlist in there like I don't want a playlist track I want just a track and in 14:00.040 --> 14:06.840 GraphQL I can do something like this I can get a playlist I can get the owner of that playlist I 14:06.840 --> 14:13.960 can get the playlist of that person so for an example for me I would have to playlist 14:14.840 --> 14:21.960 one about Java metal if you don't know Google hello world.java in Spotify it's very good you 14:21.960 --> 14:30.520 want to regret it and another one about Belgium classics and so if I do that forever like 14:30.520 --> 14:35.640 if I use the same object everywhere like I have a playlist referencing a user but the 14:35.720 --> 14:41.800 user has a playlist and so my back end will go in a nondless loop because it's going to 14:41.800 --> 14:49.400 recurs forever but the only way to break this is to make two objects so we would have simple user 14:50.120 --> 14:59.560 and a regular user same thing because rest is about resources it returns big gisans and sometimes 14:59.560 --> 15:06.120 you don't want all the gisans that are like sometimes you just in a screen that is very small 15:07.080 --> 15:14.760 so you end up with a lot of different variants for the same object so you have the track object 15:14.760 --> 15:19.560 simplified track object linked track object please track object and this is real that 15:19.880 --> 15:26.520 from the Spotify API and in graphical world this feels a bit weird because 15:26.520 --> 15:33.320 really what we want is we want just one of right and this is where it becomes a bit complicated because 15:33.320 --> 15:40.520 the only way you can do this is by manually looking at your open API schema and 15:40.520 --> 15:47.880 merge the types that go together so here for an example I call them entity because they all 15:47.880 --> 15:55.000 shares the same ID and from a ID I can get all the information and all the fields for the 15:55.000 --> 16:01.480 subject so I can iterate the small objects it is the thing that really is track object is not 16:01.480 --> 16:10.120 a track because it can also contains podcasts and so this is a lot of manual work and going into the 16:10.120 --> 16:16.840 schema that cannot really be automated like you really have to augment your schema so maybe with 16:16.920 --> 16:24.280 something like overlays we could do something but right now it's very automated very manual sorry 16:25.240 --> 16:33.720 so this is like the moral of this story going from open API to graphical is a bit like this triangle 16:33.720 --> 16:39.400 here like when I started this effort to once go I was like sure it's schema it's all a 16:40.440 --> 16:46.440 machine processor also I can take one and convert it to another one automatically but 16:46.600 --> 16:56.760 it's not 100% automatic like you have some manual fine tuning to it's not all dark so 16:57.640 --> 17:04.120 if you follow if you are an open API author here and you want to make your graphical people happy 17:04.120 --> 17:10.840 and maybe also your個人 people happy because everything I say like graphical is a type system 17:10.920 --> 17:18.600 but every language has its type system and interfaces like in terms unions all of that this is 17:18.600 --> 17:24.840 something that you will find in a lot of languages like Kotlin Swift type script and because 17:24.840 --> 17:32.120 open API is so flexible sometimes it makes it hard to generate code from it but if you follow 17:32.120 --> 17:38.920 you guidelines like using operation IDs like to be able to give names to your to your objects 17:39.000 --> 17:47.080 use components also to share code share properties make sure to document nullability required 17:47.080 --> 17:55.960 and use all of one of it makes it a lot easier to bridge the APIs and to generate code automatically 17:57.320 --> 18:03.560 on the do not use parts I talk about any of non string enums I mean some language might 18:03.560 --> 18:10.680 support it it just happens that Kotlin doesn't so there's some versions of non string in them 18:10.680 --> 18:18.120 I think intergers in the Spotify API that yeah well we cannot support a nested one of because it's 18:18.120 --> 18:22.360 blows up like it explodes as a number of types you have to generate. 18:23.000 --> 18:33.720 wrap up Mondatory slides both GraphQL and Open API are very good strongly typed ways to 18:33.720 --> 18:41.000 describe your API there is one big fundamental difference which is one is also a query language 18:41.000 --> 18:47.960 in addition to being a schema definition language there are few philosophical differences when it 18:47.960 --> 18:54.440 comes to versioning and evolution and how you manage your endpoints but the types of systems are 18:54.440 --> 18:59.960 really similar and you can map from one to the other the end of the day I would say if I had to 19:01.560 --> 19:07.800 wrap it up that GraphQL is more concise and expressive and Open API is more flexible 19:09.400 --> 19:15.160 that's it for me and then one last thing is that GraphQL confis happening in Europe this year for 19:15.640 --> 19:21.800 many years I don't know when when was the last time it was in Europe so you can buy tickets you can 19:21.800 --> 19:28.920 also talk to Benji at the back of the if you're interested in being involved it's very cool and 19:28.920 --> 19:32.760 I'm very much looking forward to meet you so thank you very much