About this talk
This talk focuses on the importance of REST APIs and the speaker's extensive experience in developing and maintaining them. Rousam discusses the transition from SOAP to REST, emphasizing the advantages of RESTful services, such as simpler error handling and better serialization with tools like Jakarta MicroProfile. The session covers best practices for creating REST APIs, including defining HTTP error codes, implementing versioning strategies, and ensuring effective documentation using OpenAPI specifications. Rousam also addresses security measures that should be incorporated into API designs and discusses advanced patterns, such as implementing pagination, bulk operations, and the differences between REST and modern alternatives like gRPC and GraphQL. The talk concludes with insights on how to manage API deprecation and the significance of monitoring API usage.
Full transcript
Let's get started. So, um I would like to talk about APIs. And first of all, I'd like to start with just question. Any developers here? Yes. Have you used APIs? Good. Perfect. That's exactly what I wanted because everybody goes hands up. So, your hands are working. I want you to use those hands. if you have questions, if you have comments, if you want, just don't wait till
the end. Let's just do it more of a um kind of conversation style instead of just waiting till the end and asking all the questions. So um I I've been working as a both developer architect uh also as a consultant and also in-house uh developer and you know doing all different kind of things and this talk is a mix of uh kind of you know the experiences
that I've had I for a while I worked for um as an in-house developer for a bank so we used a lot of well rest or other web services um you know a lot of legacy a lot of leading edge and a lot of mix and then I also done a lot of other um customers being a consultant and doing like projects and working with things like
that. So this is a mix of all those things. I my name is Rousam. I'm based in also in Norway. I I live there. I work there. Um uh I'm running some communities there as well. And well right now I'm also um uh working as a cons back to being a consultant again. Right, let's jump into that. So now that you can you know that you can
stop and ask me a question at any time please do so. It doesn't have to be a question can be comments and everything like that. So the main kind of idea is well you know since we're talking about rest we need to kind of talk about what is rest what is rest full you know all these kind of things restish I guess there is a thing right
and I would like to talk in general about how to maintain and build those kind of APIs um a lot of things that I'll be talk all of the things that I'll be talking about will be showing examples based on jakart microprofile things like that uh so a lot of eclipse foundation kind of stuff But if you're using something else, if you're going with, I don't know,
let's say Spring Boot or anything else, you can still apply all of those things there as well. So, you know, it just may be a little bit different syntax, maybe a tiny little bit different thing. Um, first of all, I would like to start with this. Anyone want to give me a guess what's it about? Soap. Yes. Anyone used soap? Anyone enjoyed doing so? That's a good
So I did the same question yesterday in Madrid. There were no hands. I Today it's one and a half hand I counted. So there was one and then the other one was like this. So kind of it counted as a one and a half hand. That's really good. That's really nice. I did use it recently like last year uh during the latest during the the the well
360 something days back right. Um I not sure if I enjoyed it but it worked. Um right so I would like first to start before Oh yeah this is um this is a place there is a hotel in Poland in Kov that has this in the bathrooms. I'm not sure they're talking about the same soap but I really love this picture. I always like every time I
end up there, I take a picture of it. I think I have like 10 different versions of that picture and all of them are blurry for some reason. But you know you can all apparently you can use soap and sing some people say I think it's a different soap but you know I I choose believe different um right so but the thing is that now we have
rest services right so now the rest is here and now we have this way of developing and you know creating services and all the things that we kind of didn't really enjoy was so they're kind of gone so now everything is good right so now we don't have to think about the talk is done. We can just go home and be happy about it. Well, maybe not.
But before REST, you know, there were things like uh WSDL or Wistl, which I kind of really liked. I don't know if you like you can agree with me or not, but like for me it was kind of nice because well, I mean it was verbose. It was XML. It was just like a horrible thing. For those of you who don't know, it's basically the contract for
the service, right? So you where you would provide uh what parameters it can take in what parameters it can return the data types you know all these kind of things everything uh we don't have it necessarily that strict in rest yes we have open API spec and all that we'll talk about that in a second but it's not as strict as that before you could just point
at code generator at it and we'll generate your code bunch of folders uh everything will be generated but then you had a problem that uh those of you have you done that right? You would generate code and then like what do I do with that? Do I commit it? Do I just regenerate it every time? You would probably most of the times end up just regenerating it
every time. At some point the libraries would just go out of maintenance date, you know, break things. So you would try to upgrade things and upgrading things would just break. And then you finally after like lots of searching and replacing things and everything you would end up you know finding the correct version of that library that was breaking and then you generate code and it's like okay
never again I'm just committing that you commit that a new person comes into your uh project junior not junior doesn't really matter and decides to modify that code right anyone really no never happened okay well lucky Um, and then you're sitting there with committed codes that was generated at some point and was maybe or maybe not generate modified. So you had to go through logs and stuff
and uh, you know, try to figure out what it was what was going on, right? But then, you know, we don't have that now anymore. The good thing actually, well, the good thing was the the thing I kind of liked was the wisd thing and the other thing was that well, I mean, it's a bit logical thing, right? You have envelopes, you have headers, you have body.
So it was kind of structured in a way, but still it was XML. Right? Now we it's a different story. So this is a just a screenshot from my ID. That's why it adds my name everywhere because committer name of the commit code. So just ignore my name there for a while. But uh um kind of weird to show slides. So it's just your name all over
the place. Uh but um the point is that we're still kind of generated code but it's in a background. We don't see that. Now you can actually create and define a rest client. So you can do that uh just with saying register rest client and then it will just like bam just give you you know you can just define some endpoints. You can even define failovers and
fallbacks and all these kind of things and it will just work. you don't have that code that is visible that's easy to modify and everything which is nice right but then you have also uh automagic serialization between the objects Java objects and JSON so you have JSON B JSON P you know all those kind of things right so it's really nice that part is a good thing
um so now that we have rest let's talk a little bit about basics and with basics um well obviously we can put different things into it but anyone who Who wants to try to guess what like or not guess like what does it mean basics for you? If I if I say let's talk about rest basics. What first thing that comes to mind? Perfect. Yes. Very good.
Uh even more specifically what I would usually like to start is talking about HTTP error codes, right? And well, yes, but it is HTTP and JSON. And then when we use that, I would like you know the basics is for me. We'll talk about what you said in the next slide, but first just a little bit of more just HTTP related stuff, right? What is the what
is usually a problem with REST and error codes? Anyone? Have you seen that before? I mean, you're all laughing, so I my guess is yes, right? Yes. Good. Um, but you know, hold my coffee. Um, it gets worse. So, this the next thing I'm going to show you is a actual code that well, for obvious reasons, I anonymized very much, but it's actual the same error and
everything that I got uh from some of our backend systems. And I split it up to line by line just to for a bit of a dramatic effect. So um this is a start right 500. So HTTP 500 that is a server error. It's not you it's us kind of thing. Right. Right. So the response. Okay. So far so good. That's first line. All right. Second line.
Well I mean we knew that. Right. Um, third line. Oh, this is getting exciting. Are you excited as I was? I was not. I mean, I was really Okay, can we please stop doing that? Pretty please. So, my service was just like the thing that I was trying to debug was using something and it didn't respondse with a proper thing. just gave it 404 and then it
was like, "Oh, I got 404 crash." And well, I mean, it's it's really weird because like it's one thing is that we're returning wrong error codes, but it's also another thing is that it um it doesn't do failovers. It puts a lot of logical like information into a message, meaning that you need the supervision to to actually understand what's going on, right? So there's so many things
that are wrong with it but you know and then so yeah well this is not really fun thing right um but then we're developers right so we are just uh we're very good at this thing called it's not bug it's a feature as long as we document it so next thing is a a screenshot that I got uh so this is a screenshot that I got from
a friend that took a screenshot so it's like a meta screenshot um of this. So this is actual product out there somewhere uh where they said you know what we're just going to document it and say all responses including errors always return HTTP 200 so we're good and uh to actually understand what's going on you have to look for fields so if you have data you're in
luck if you have errors well too bad for you and then there's apparently there's something more there's like or something right um which is no right we cannot do that so we should actually use proper uh error codes and uh you know there are a bunch of codes and there are a lot of really useful ones and we'll talk a bit more about that in a second
in a in a bit but the point is HTTP codes are kind of an important thing for rest I would think I would argue for that anyway But then you know the basics if we're going to bit more from Durant to a bit more of a Jakarta kind of patterns or just generally pattern I mean if you even if you use Python you'll end up with something
like this right uh you'll have a path you will have a verb like get put post delete whatever uh you will also have some kind of content negotiation you would say you know what I expect what kind of data um I expect to have what what kind of data I'll u produce Um I you can add some bean validation things to to for for well for obvious
reasons to validate things and then you can also get serialization all that and then if you really want to test all those things it's kind of nice and easy way of doing that. Well obviously you can test in your machine but this is not the way we do things nowadays anyway. It's much better to actually test it in a real proper kind of environment. So probably put
it in the container. uh if you have several services talking to each other maybe compose kind of file that would be very nice to use for this if uh if you're doing it a bit more on like end to end testing and bit more larger scale test containers kind of be can be a very good thing to do that because then you can just you know create
those ephemeral containers test everything and just kill everything afterwards and then you every time you test it you start with fresh uh fresh from the fresh page right fresh beginning um yeah like I said the the verbs get, post, put, patch and delete. Most of the times you will see get and post, but then there are actually more and those are very nice to use. And then
you have also content negotiation thing, right? So where you're just saying, well, this thing produces uh JSON. Um, another thing that we don't really talk often enough about, I think, and I don't really I'm not going to push you into like a full uh like super super advanced uh hypermedia kind of stuff, but I'm just going to mention that's there and I'm just, you know, try to
encourage you to see if you can in some into your um next application. So, typically say, so this is a very very simple example. Say you have some kind of service that returns books or gives you some kind of information about books and then uh typically you would just create something like this. You know what? I'm going to return an ID. I'm going to return a title,
an author, maybe some more data. That's it. Right? Good. If you want to go a proper kind of hypermedia way, you can add more links to it. And this is kind of really nice because then it gives your both your systems but also you as a user as a human being reading that response uh and understanding what you can do with that stuff, right? So you can
actually say you know what uh link to myself is that a link to all of the books that you want to you might just want to have is slashbooks. Normally you would just end up guessing, right? But this takes guessing out of this equation. Um, also which is really nice which I usually like and I hate G guess guessing is that what kind of operations I can
run on those endpoints. Sometimes things are not even documented properly, right? And then you're like, okay, can I do update and delete? That's all one can do here apparently, right? Um, I worked with APIs uh that are that we have to integrate with, we have to send data to and then you would be like what can I do here? Is it just get post? Uh, can I
do put? Can I do uh update? Can I delete? Oh, no. It failed. Ah, okay. Well, I guess I can't. Oh, on the other endpoint, I can do that. Okay, cool. So, then you just have to try and guess, right? This is a nice way of doing that. So, I'm going to I'm not going to sell you more of that idea. There is more there. Like people
really go full hyper media way, but at least there is there is that Then there is this fun thing of versions. So another thing that I would like to talk about is versions and versions most of us have used versions and the most common version way what is what is the most common way of versioning things for you? Sorry what yeah like in in URLs right but
then yes but that's the thing right but then there is more there is actually a few more versions so uh the the the URL versioning is the the path right you just add v2 v3 v whatever but then you can also put it into headers I mean what kind of versioning is it's a different sort right so if you use semantic versioning or something else it's it's
it's fine right you can you can do whatever you want you can call your version panda I don't know I don't it's fine uh it doesn't need to be like any specific but how you define it is a bit different right most of us would just think well path it's always v2 v3 v whatever but then you can also put them in request headers you can put
it into media types those three are quite legit based on your use case this last one is I'm not really sure if it's I want to encourage you to do that it's kind of weird and it's very confusing But it's possible, right? So technically you can also put it in the request request parameters, but that don't do that. Please, unless you have a very very good reason
and you've like really tried all the other things, please don't. It's just confusing. But then when you create versions, we need to talk about another important thing that we kind of sometimes forget is that we need to deprecate things as well because you will end up creating a lot of technical backlog or technical depth really because all those versions will be there and then you have to
maintain all of them at some point, right? Um okay. So um three versions that I'm going to show here and also the way I do that is that I just show you a little bit of code for path. I didn't show you much code is because it's just at path. Uh but then I at the end at um in the corner here I'll show you I'll give
you also an idea of um how like a curl command would look like and also how HTTP file would look like. Same thing just a different syntax but so you can actually find whatever you feel more uh relatable to what you what you how you're used to do things. So with the with with with versioning thing it's pretty easy right? you just say, well, you need you
need the accept header and saying, well, you know what? I'm going to accept JSON, but um you just say V2, V3, V, whatever, right? and then you have a bit of a different bit of a a problem here, right? Because now you have to um like what are we versioning? Do we put the version one and two after API or we put it for each resource or
different endpoint like what are we versioning? What deserves a new version? How do you do that? If you just update one resource, is it just a new version all of all of a sudden or is just like you know basically where you would put the V2 just right after API there are many ways many things to think about if you really want to go philosophical right and
then it was like somebody asked me once I was when I was doing the talk it was like um let's say the resource was books right like we had in my example it was books but is it books or and then you do slash one or is it book slash one so you can go really down the rabbit hole really and then you can like you know
I'm just giving you more things to hopefully not keep you sleepless at night but still to think about um custom headers is a bit different right so customer headers is less visible in a sense that you cannot just look at the URL and say ah it's version two now we're actually using the same URL but we're sending in in a header. So before we just had accept
JSON, right? But now we're also doing accept version two and then you can receive it like this is how we inter it would look like you would just being receiving that uh as a string for API version and then um uh from from the like mapping it from a header param putting into in the API version and then you can use it in your code. So in
this case I'm just printing it out right but then typically you would do something more useful with that um but so custom headers and then there is also the thing with media type that is even more probably okay let's do this path how many of you have used path I would yes yes exactly mostly mostly custom headers anyone okay media type that's the opposite That's really good
because usually I I actually see it the other way around. There will be more hands for headers and then there will be like few for media type but it's really nice. So media type is a bit different again right? So then you actually say but the cool thing with media type is that you can actually provide several you can do list of things you can say you
know what if somebody calls you with this type of stuff coming in uh then you can just uh invoke that method. So here for example this one will be called uh for version three and four one and two we don't know five six whatever we don't know but three four that that's the that's the method for you so that's kind of nice but the notation will be
again will be a little bit different right so you still say except but instead of just saying except JSON you actually say some kind of version there um right and then we talk let's talk about application because now that you've created bunch of versions, you need to start killing old ones because you don't like I said you don't want to maintain all those versions all the time.
Um, one thing is that you want to update the docs and the docs by docs I really mean we'll talk about that I actually mean like something like open API spec that is code close to the clo code near docs not your web conflence word file docs probably you shouldn't have those to begin with but you know well you can update those as well but um something
that's close to your code that you can generate from your code and expose it to to your uh customers, users, whoever is using your API. Uh you should probably try to add at deprecated to your methods because then the ID will pick it up and stop other people from calling it and using it. Maybe at at least give you like a strike through and like you know
some some kind of warnings. Um, at some point, not maybe not right away, but at some point, you can go a little bit, I don't know, kind of passive aggressive and start start returning uh different redirects and say, well, I told you so. Now it's time to actually say, well, temporary redirect. Maybe at some point you go even like one next step of passive aggressiveness and say,
well, it's moved permanently now. uh or there is I I think I think there is more in 300 series that can help you with that. I I I I have a I think there was something like with 308 but I don't remember what it is. By the way, speaking of error codes, anyone knows what 418 is. Yes, good. I'm it's it for those of you who don't
look look it up. It's quite fun. It started as a April Fool's thing uh when they were writing the spec and so they they had a a number uh left over it was 418 they put it there and they called it I'm a teapot so whenever you you can actually put it in your code and legal HTTP error code and it will just say it's right back
to the precation things uh so what you can do also with deprecationing things is that you can also provide a link I'll show you how you can do that you can provide a link to a better to a newer version not better but newer version uh in the header and also another important kind of thing is that things that we kind of sometimes forget is that we
need to log and count the com uh number of calls that those APIs are getting right because uh if you know that this is being deprecated but still a lot of calls are being made maybe you want to do something about it like track down who's using it maybe you have some kind of API keys they're being used so you can track down who's using it or
how it's being used and so on so on and try to do something about it. So matrix is an kind of an interesting thing, right? So in a code and yes it's a wall of text but I put some arrows to show you a little bit to help you a bit to kind of to parse that wall of code is that you know you cannot put word
deprecated enough times right so then we have a word deprecated in at operation so at operation that's something comes from open API spec right so uh from open API I think so then we'll generate a a a description there and then there is well there is a there is a summary and the description fields and both of them have deprecated in it. Um but that's just text
that's for humans reading it right. Um then we have at deprecated then we have a uh this link thing that I'm talk I talked about right so this is um um this is where you actually create an an alternate link and then say you know what my UR URI is version two this is the latest version and you provide that as an alternate link and then you
you you pack it in or bake it into the response header um documentation. Let's talk a bit more uh about that. We talked a little bit about that already. Um so with with with Jakarta microfile things is there is this open API uh package and this is really nice because it you don't really need to do anything but like kind of like this right you just say
oh by the way I need to let's go back to here for a second. So open API thing is the operation thing right but then uh thing I forgot to mention is this at counted at count this is the at counted this is the um the metrics thing. So when you when you do that and you call it something so for example this one has a very
short and sweet name of total count to random pair calls underscore version path deprecated right and but the point is like whatever you give it the name of that it will show up with that name at slashmetrics for your application which is really nice you don't have to do anything else it will just count and then you can just define if it's the absolute count or different
like different version of how how you want it to count, how you want to describe it and so on so on and you can also add tags to it. So then you can actually create create different tags with for different things or use the same tag for in different methods for for example give me all deprecated ones and so on. Okay. Uh back to documentation. Uh so
uh with open API integration, you can just do things like that. You can just say add operation. But you can actually provide more. I'll show you in a second. And then uh before that I want to talk a little bit about this what we talked a bit about already the annotationdriven versus kind of static documentation right because uh before we used to do that a lot. Now
it's getting hopefully I think it's getting a bit less of that but it still is a thing is where we um start to start at a project and then we ask like do we have documentation people be like yeah sure it's on that before we used to call them network drives now it's like cloud drives but it's the same thing right it's like the word files that
nobody touched for like 15 years then you have to blow dust of them and just like the the scrolls of elders and you know all this kind of stuff. Um but it sucks right because every time you actually put that into a document it will just get outdated immediately pretty much because you will at some point forget to update. If you put it into something like open
API it will just regenerate every time you um generate it. And then you know you have things nice things like swagger and stuff that's built on top of that that basically uses the text files that open API spec produces and puts pretty um you know fields and buttons and colors and stuff to it and generates the swagger thing that we know and uh use hopefully. Um right
and then we have this thing uh of you know if you want to code first and generate doc or you want to generate actual open API spec and make sure that the code you write kind of plays well with that that's that there is that thing um and also you can use the documentation as a living API contract right then you want to you remember we talked
about the WSDL well this is kind of the closest thing we get to this but then there is also um um what's it called uh CDC consumerdriven contracts. So you can also do this kind of things, right? So you can um actually use those contracts or use those uh docs and then generate or write your code to it. So think of it as a a kind of
weird way of doing TDD, I guess. Maybe I mean at least you have a what where you want to be and then you try to match that. um you can put a lot and this is just a simple example. This is a screenshot from the doc. So um the kind of important thing to that I haven't mentioned yet is that both Jakarta and microfile their specifications it's
up to providers whoever that is if it is a pyro or if it's Helen or Caucus or whatever is to to say when they say that we support it is they basically implement that something that satisfies that spec and the the the the link to the spec is very short and nice and it's just there on a side I expect you all to remember it right Okay.
Uh but you don't have to um you can just search for open API spec and micro profile and you'll find it. Don't worry. But the point is you can actually so the upper thing there it's a code. So this is how you do it in a code and the bottom thing is that how it will just generate the output from it. So here you can actually provide
things like um possible response codes. see like at API response you can say well you know what if you're getting 400 that means in this case apparently it means user not found okay and if there is some other response code then it means something else so you can actually explain those things and they will show up there at the bottom right so you say um you know
what verbs do I support well I support get what is it a summary and blah blah blah and what parameters it takes what types of data types of par the parameters have uh what kind of responses it gets, what uh what kind of object it gets back, right? Um what kind of errors you can have and all that is just there, right? And then you put that
and then you have like a swagger UI on top of that, it will be um security. So let's talk about security almost at the end of the the talk as you know we're all good developers do we slap on security at the end and hope it sticks um but actually in my defense it's not all all the way at the end so you know I I tried
but it's actually a very important topic right and it's two things so two different uh parts of it it's one is that when you're creating when you're talking about security is that you create your application to be secure but then it's also about uh making sure that your well you know there is like this thing of data integrity and data uh availability and all this kind of
things. So you want to make the data available to people that need to have it available and then you also have to have make sure that it is in the integrity of it so nobody cannot modify it whenever they don't have to right but then there is also something else we'll talk about that in a second so first of all you know all this thing I said
is uh all this um authentication authorization and all this kind of things you get from Jakart which is really nice uh if you want to do with J J J J J J J J J J J J J J J J J J J J JWT uh tokens and all that kind of things and you want to play around with the integration thing. Uh there is
for example way of doing that with microfle JWT. Um you can also do role based stuff. So arbback right you can say you can annotate your endpoints with you know at deny all or at permit all and at only roles allowed blah blah blah. So you can actually do all those things kind of automatically, right? It's it's kind of nice way to to to to control that.
You can declare roles. You can also have this object that's getting kind of in injected into your stuff with security context where you can actually say well is this user in this role or something Um so this was about creating your application to be secure. But then there is also um two different level different side of it is to make sure that your application is harder to
hack for two reasons and one reason is obviously inputs. So you want to validate your input stuff um for obvious reasons, right? So basically uh the the most obvious one would be something like SQL injection. So you can actually squeeze in some kind of SQL in there and if you're doing something really fishy at the at your back end that SQL injection will go all the way
down where it's not supposed to be and give you the answers it's not supposed you to give. Um, but it's also about validating and cleaning your output because when you're returning some output, again, the most extreme case would be just returning stack traces. But even a little bit less extreme ways of returning errors will actually tell you quite a bit about what this version is, what the
system is running on, how it works, you know, all these kind of things, right? And you don't want to do that either because then it will be easier again to your system to be hacked uh for your system to be hacked. Um well you know another thing that you want to think about when you create uh services rest services uh or restful services is also who can
call your stuff. So like cross origin resource sharing and all this like you want to be permit calls from different domains not and so on so on so on. Um software supply chain security that's a different story again but and that applies to any kind of software really but also for endpoints. If you know that those packages that are there are some kind of vulner vulnerable in
one way or another you need to think about that as well. And there is a little bonus here that uh is kind of nice because um so there is this thing called uh um OASP top 10 for web and all this. That's what we've been all shown everywhere and told everywhere to to to like to um to look for uh but now they've created bunch of other
things. I mean it's not now they've had it for a bit but many people have Okay. How many of you have seen the top 10 for API security risks? Oh, that's very nice. Okay, good. Perfect. Then I don't need to sell you uh that idea. But there are those and there is also one for the one that I kind of played around quite a bit also is
for AI which is kind of also fun but that's a different different talk. Uh but those are yeah we'll get back to that right. So uh a little bit more advanced patterns. So I and I put air quotes. It's not really air quotes, but there are air quotes uh for advanced because they're not very advanced in a sense because uh but I don't see it enough. So
I'm just mentioning it maybe it will fit your user uh your pattern and maybe you can use it. Uh so there is things like for example you sometimes you need to implement pagation not always but sometimes and sometimes you don't want to uh return the whole world. I mean very often time oftentimes I see like if you ask for let's say all the books it will just
give you all the books but if you want just one you don't and you don't know the ID of that thing it's kind of hard to filter but you can do that here so you can do page nations for example so defining offsets limits uh saying give me everything after a specific ID uh and so on but you can also um add filtering parameters so you can
say give me all the books where author is Jane Doe and year is 2020. Uh you can also provide sorting parameters and also you can also say if it is ascending and descending. So it's kind of fun. You can do things that I I don't see it often enough. Maybe it seems like there is a lot of people that play and work quite a bit with API.
So maybe you have done that but if you haven't this is the thing. Uh another thing that I this is a bit more relevant. So this is a bit more relevant in a kind of enterprise context. Um this is um when you run long running jobs. How many of you have submitted something to something that takes some time and got the spinning wheel and then you're just
Yes, exactly. Perfect. Pretty much like all the room and then you're like what's going on? You wait for a second. You wait for five. You wait for 10. You go grab a coffee. come back and then you're like, did it crash? Did it like you know, you know what I mean, right? And this is this is the solution. Can we please do that? So now I again
I split it up a bit too much. So I have like three steps since you could probably squeeze it into two, but I just did it just to like separate things. You don't have to do that. But the point is you you you submit a post to um to reports. It gives you received 202 and it gives you an uh location and ID said hey your request
has got ID 123 here it is and then if you want to know more about it you can go from now on you can go to report123 and then if you go there it will give you I some kind of status processing done error whatever and then um when it's done or when it's error when when it's errored or something like that you can go to slash
results and actually see what's going on. Those last two, you can join them together, I guess. But I I ended up splitting it up. Um, this is a very nice thing. This would like a lot of users would probably appreciate it. I would definitely say that's another thing. Bulk. How many of you have used bulk? No. Um maybe it's a good idea depending on your use case
but very often like I've ended up creating curl well putting everything in a file a thousand lines then using the curl command with the proper thing to read from file and root loop through all the elements and then call all these things and add blah blah blah right sounds familiar maybe yes if you implement bulk if your use case applies to that you can actually do that
and provide a list of things and then you just do one call, one list, and then it will do that. In this case, it's transactional. So, if something fails, it will actually revert everything, but maybe it's a good thing depending on what you want to do, how you want to do that. So, there is a little bit uh of stuff beyond rest. So, I don't want to
like just sell you all the rest. There are some other things, some other things that can help you. And uh there are well generally mostly it's two things is gRPC and there is this thing called graphq, the short version is that if you want to do just regular CRUD, so create, read, up, update, and delete, go with REST. It's good enough. It's nice. It's readable. You know,
it's it's like human readable, computer readable, all good. If you want to go performance, if you don't mind if it's the the format is binary, if you have client server kind of communication, if you're doing some kind of streaming, you need structure and all like you know all those kind of things or like you know strict structure. Um gRPC is your friend, right? If you're doing like
high transaction, high latency, sorry, not uh the opposite uh the low latency application and all these kind of things, gRPC might be your friend. And then you have this kind of thing. If you want to create one endpoint to rule them all kind of thing, maybe graphql is a good thing because then you can query things. And if I'm not mistaken, correct me if I'm wrong, but
I think if I remember it correctly, so one of those top 10 API things was that be careful with what you provide. Well, well, what you let your users do and then you can just so you can basically do yourself by just letting users to ask for too much. And uh if that applies to all of them really is also for REST and all the other ones
but especially for GraphQL because then you can just basically ask about the whole world and it will be like break which sucks. Um so be careful with that. But then it's very nice to create um you know when you create endpoints for BFFs well it's a kind of a bad joke but um before BFF used to be a best friends forever you can create your APIs for
your BFFs in GraphQL that's fine but in this case it's actually back end for front end uh so you know um you've been warned it was a um but um it's it's very nice in a sense that the front content can query different things and you don't have to create those crazy too many uh too many detailed APIs right um a few links so there are a
few links for so the code that I've used in this presentation and everything it's in the repository called random strings on my GitHub um another there is another more advanced version of this talk oh not this talk but like a next step from like uh uh building APIs and all these kind of things uh it's called an opinion ated guide to bulletproof bulletproof APIs. The code and
the slides slides are in the same folder in the repository uh ink doc. So you can actually click through them in in in your browser. It's there. And then there is a blog post on just about the versioning that I posted two days ago. I think it's there. But if you want all the links, if you don't want to look for my blog and if you don't
want to look for um the GitHub and everything, if you just scan the QR code, it will take you to. you'll find all the links. It's basically all the links that you might find me on social media, find my GitHub, find my, you know, all those things, this is what we've been through. We've what was before REST, the basics, the versioning, documentation, security, some advanced patterns, some
some things And well, this is pretty much it. This is what what I have. And like I said, if you're interested in a more advanced version and like more kind of next step where you would talk about I talk a bit more about separating different objects. So your REST objects and your domain objects are separate and all those kind of things. It's just go there and you'll
find my GitHub and then you'll find it there. It's called the Java API. Uh it's pinned on top so you'll find it. Any questions, any comments, anything before we call it a day? Anything you want to share with others to learn when we talk about Rust and stuff? Anything that bothers you that everyone keeps doing and then you're like, "Come on, people. Stop." No. All right. Well,
then thank you very much. Enjoy the rest of the conference. Thank you for coming.
