I'm going to talk a little bit about two very popular API technologies and try to bridge
what's the name of my name is Martin. I love bikes and bananas and I do love GraphQL so small
disclaimer here I'm pretty new to the Open API world but this is an exercise like what's
happening when someone that does a lot of GraphQL tries to look into Open API so hopefully
that can bring some interesting discussions and if I'm saying something stupid please let me know.
I'm working at Apollo on this project called Apollo Kotlin which is a GraphQL client for Kotlin.
What Apollo Kotlin is doing is it takes a GraphQL schema, it takes an operation, so query,
process everything all together and generate Kotlin so Kotlin is a I level general proposed language
mostly use Android but you can use it everywhere like iOS back end, lots of places
and it's all type safe so you have your GraphQL server and you can be guaranteed that
your query is going to run all the way from your back end to your front end without any bugs at
least in theory. It's a very low level library so in order to showcase it and to showcase like to
make people use more GraphQL my web colleagues did this cool stuff it's demo using the Spotify API
so it showcases all the Apollo products and GraphQL in general like federation, router and all these
kind of fun stuff and it uses Spotify which is something that we all know we all know what the
playlist is we all know what the track is so it's a cool model to use and Spotify has a very cool
rest API it's very well documented and it even has an open API schema on the right here following
the previous presentation I run it in right my API and it's good it's a good rest API
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
what if I could take this open API schema process it automatically, turn it into a GraphQL schema
and API and then do the same thing with Apollo Kotlin because at the end I want to have fun with
Apollo Kotlin and so I would have a full end-to-end like from rest to GraphQL to my clients my
Android app so this is like again it's very small but we are going to look at some portion one after
the others. Lorna talked about it I hope you know about open API it can come in boss
Yamal and Gison like this is a Yamal version and what I'm suggesting is that we take this like open API schema
and we turn it into a GraphQL API so that's our goal for today.
If we take the first line this is info that Lorna was talking about earlier today
that tells a bunch of information about your schema like the open API version
the version of the Spotify API itself one dot zero dot zero by the way it's not using the latest version of the
spec so if someone works at Spotify here probably time to update I guess there's a title and a
bunch of URLs here there is only one but this is where you can make your API calls.
Well in GraphQL it's a lot more easier because we don't have such melalata like the wall spec
isn't really version it's always backward compatible and
feature discovery is another story but you can get most of the feature discovery using something called
introspection where you go to your URL and you get the schema author it's a new version for the
schema for the Spotify schema either because like GraphQL uses more fluid philosophy of using
deprecations or if a field well you evolve your schema through deprecation you first deprecate a field
and once it's not used anymore you remove it and you add new fields when you need new features.
Well else no URL in GraphQL because you have one single URL it's your main GraphQL URL it's your main
endpoint and this is where you also get your schema from so it would be a bit redundant to add it
also in the schema like it would duplicate information so in GraphQL you have this schema and a
root query type where we are going to add some stuff. Now the interesting stuff like how you get your
data in open API you have a list of paths which are really roots where you get your info your data from
this is an example of using a playlist if you want to get a playlist so if I go there
it's a get operation the schema author was very nice to include an operation ID this is going to be
important we'll see that in two minutes and you have parameters ID it's in the past and
it's completely types of the string here and you get back a response which is jason and which contains
a composite object type containing a playlist so fast a good so the way you would do this in GraphQL
is you would take every pass and you can turn this into what we call a root field so in that case
I took my root query object here and I have a root field called get playlist here this is where
operation ID is important because if I didn't have that I wouldn't really be able to find a good
name for my root field I would have to guess from the pass or like I don't do some machine learning
whatnot but the operation ID gives me something user friendly there input parameters same thing I have
strings so the type system is really really similar it's really easy to map from a jason schema
and open API types to the GraphQL ones and it returns a get playlist object which is a game
I don't have a good name for it so I decided to is that something stupid on the slide?
No, not a good. You tell me if I say something stupid I would open API.
So for the output type it's yeah I reuse the same name as the field here because I don't have anything else
so it's a gate playlist so it returns a get playlist why not and then we are going to put some more
fields inside so if we go inside the playlist object we have a bunch of properties
same thing by the way I did not mention but even the descriptions map really well like here you
have an open API description and you have the same thing in GraphQL on the right so it allows you to
generate documentation very easily and have the same documentation in both worlds
well that's it's really easy for simple scala fields you can have a raise so if you have a
list of tracks in your playlist here with a bunch of items which are tracks in GraphQL this is
done using list so we use this square brackets here so the list and same thing here always naming
complicated right like in software engineering it's always the same problems so for naming
my object my composite object I used get playlist track so using the enclosing object and then the
field so that it we have our nice schema we can take things even a little bit further because both
GraphQL and open API support no liability so if you had information about no liability in your
open API schema it will be included in your GraphQL schema so in the left you can see you have two
keywords actually you have a required and a new level for the most part GraphQL doesn't really have
a concept of required field like all the output fields are required so if you are schema designer
doing open API I recommend you always mark all your fields required which I didn't do but
I still always send the field so I just went ahead and assumed that we're always there
that's it there's one thing that is still a little bit strange is that you know I still have
this get playlist and get playlist track like my track object is still nested into very deep into my
my root pass my root endpoint and this is weird right if I want to reuse my track somewhere else
like just getting a track how do I do that and in open API there's a cluster which is called
components which allow you to do exactly that so you can do it with responses with parameters
with schemas so composite types yeah there's two version of schema like you have the
gizzen schema and the main big schema but I will talk about composite types easier and so if I take
back my schema here I can just flatten it by using component so beware group now it's flatten yeah
it's a bit small but what's that doing it it's basically referencing right basically
or reference it uses this dollar ref syntax and now I can use this name and it also gives me
also good names because these names here there are defined manually so there are manually picked
so they make a lot more sense than something that would have to be machine interpreted a machine
generated anyway so we're all good oh I forgot that once we have components we can use we can
do cool stuff with reusable components like polymorphism in GraphQL you have interfaces in open API
you can do that with all of because if a if a no-brake has all the fields of another one it's
exactly like inheritance so here I have an album simplified album object which
depends on album based and it does not depend in open API world but it takes all the same
fields so technically it's it's all almost like an interface and in GraphQL you would do it
like this so you use this implements keyword and the same for unions GraphQL I use as unions
and this maps really well to one of I'm not mentioning any of here because that doesn't
map really well to GraphQL if you use any of like it it becomes it generates a lot of types
because we have to make all the combinations for all the different possible values so looks like
we're good we took our initial rest open API schema and we have a matching GraphQL schema
completely typesage with the description all good but if you're doing GraphQL like there's
something that is first a bit weird there is that in GraphQL really and it's in the name it's a query
language and so when you have something like this at the end of the day like the name of my
object still has playlist in there like I don't want a playlist track I want just a track and in
GraphQL I can do something like this I can get a playlist I can get the owner of that playlist I
can get the playlist of that person so for an example for me I would have to playlist
one about Java metal if you don't know Google hello world.java in Spotify it's very good you
want to regret it and another one about Belgium classics and so if I do that forever like
if I use the same object everywhere like I have a playlist referencing a user but the
user has a playlist and so my back end will go in a nondless loop because it's going to
recurs forever but the only way to break this is to make two objects so we would have simple user
and a regular user same thing because rest is about resources it returns big gisans and sometimes
you don't want all the gisans that are like sometimes you just in a screen that is very small
so you end up with a lot of different variants for the same object so you have the track object
simplified track object linked track object please track object and this is real that
from the Spotify API and in graphical world this feels a bit weird because
really what we want is we want just one of right and this is where it becomes a bit complicated because
the only way you can do this is by manually looking at your open API schema and
merge the types that go together so here for an example I call them entity because they all
shares the same ID and from a ID I can get all the information and all the fields for the
subject so I can iterate the small objects it is the thing that really is track object is not
a track because it can also contains podcasts and so this is a lot of manual work and going into the
schema that cannot really be automated like you really have to augment your schema so maybe with
something like overlays we could do something but right now it's very automated very manual sorry
so this is like the moral of this story going from open API to graphical is a bit like this triangle
here like when I started this effort to once go I was like sure it's schema it's all a
machine processor also I can take one and convert it to another one automatically but
it's not 100% automatic like you have some manual fine tuning to it's not all dark so
if you follow if you are an open API author here and you want to make your graphical people happy
and maybe also your個人 people happy because everything I say like graphical is a type system
but every language has its type system and interfaces like in terms unions all of that this is
something that you will find in a lot of languages like Kotlin Swift type script and because
open API is so flexible sometimes it makes it hard to generate code from it but if you follow
you guidelines like using operation IDs like to be able to give names to your to your objects
use components also to share code share properties make sure to document nullability required
and use all of one of it makes it a lot easier to bridge the APIs and to generate code automatically
on the do not use parts I talk about any of non string enums I mean some language might
support it it just happens that Kotlin doesn't so there's some versions of non string in them
I think intergers in the Spotify API that yeah well we cannot support a nested one of because it's
blows up like it explodes as a number of types you have to generate.
wrap up Mondatory slides both GraphQL and Open API are very good strongly typed ways to
describe your API there is one big fundamental difference which is one is also a query language
in addition to being a schema definition language there are few philosophical differences when it
comes to versioning and evolution and how you manage your endpoints but the types of systems are
really similar and you can map from one to the other the end of the day I would say if I had to
wrap it up that GraphQL is more concise and expressive and Open API is more flexible
that's it for me and then one last thing is that GraphQL confis happening in Europe this year for
many years I don't know when when was the last time it was in Europe so you can buy tickets you can
also talk to Benji at the back of the if you're interested in being involved it's very cool and
I'm very much looking forward to meet you so thank you very much