Servoy 2019.09 Launch – Part 3 – Powerful and Seamless REST
Servoy 2019.09 Launch – Part 3 – Powerful and Seamless REST
Welcome everybody and welcome to number three in the 2019 ONA launch body. My name is gentlemen and I’ll be helping up with this webinar and Janda and he is the star of the show and presenting the other key topics of the new launch of this series. If you have any questions during today’s session feel free to post them in the questions Jailah will be there to answer them and with it out of our way let’s get started, Jann. Okay, Jan. One more time I want to show the picture of the beautiful Movin picotel and remind everyone, Sir Floyd World is fast approaching. We’re going to give some details towards the end of the webinar about this when we take question and answer. With that out of the way I’d like to welcome everyone to the third in this series launching Servoy version 2019-06. This is our third quarter launch of the year and we’re excited to bring you all of the content because this launch is packed with a lot of content. Last one we showed was on Wednesday it was all about building hybrid desktop applications. If you missed that the recording is already available. This one will also be recorded in case you want to rewatch it. This topic is about web services and in particular how to set up your own web services so not connecting or consuming web services but producing your own web services. We did a webinar on this I think it was number 17 so quite a little while ago but it’s there in our archives. I recommend if this topic is of interest you and you haven’t seen that webinar, watch that recording after you watch this because this is sort of like part two of that because we added some functionality in the latest release that extends what you can do. So I’m not going to do a little bit of a recap but I’m not going to do a full in depth about how to do web services and Servoy. I’m going to just sort of build upon that but I’ll do a quick recap and show what’s what’s capable and kind of go over a few things and then we’ll jump into what’s new. So what I’m going to be showing you in terms of the new stuff is we’ve added support for versioning your APIs. We’ve added support for top level scopes as opposed to just form scopes. We’ve added support for doing deeper endpoints so being able to do more custom stuff in how you construct your URLs and how you handle those endpoints and then I’m finally going to show you a cool extension that is sort of in the labs right now for automatically generating documentation for your API. So as always we like to jump right into the demo with this webinar and then afterwards we do some slides and recap. I am going to switch over to a tool that I like to use called Postman. It’s a web services testing tool. There are some other ones out there, some old-fashioned folks like to use curl. So anyway that’s what I’ll be using to send requests to my example web and the first thing that I’d like to do is run a quick Hello World web service and sort of show you how that’s set up because it literally takes minutes to set up a web service in Servoy. So I’m going to send a request to my local app server which is always running in background when you run Servoy developer and you can see that the response was Hello World. Maybe I’ll adjust it with a parameter and do Hello Sean, Hello World Sean and you can see that that was replaced world with Sean. Yawn, etc. You get the point. So a simple web service takes an argument, returns a message. Let’s take a look at how that’s set up. I’m going to switch to the Servoy IDE and this is actually the exact example I showed way back when we did the first version of this webinar. Here we have a bunch of group of forms and each form is its own sort of mapped resource or endpoint. And so I have the Hello World and I implemented a method called WSRead. Now the method WSRead is a particular naming convention that maps to the HTTP getverb at that endpoint. So if I do get Hello World, it calls WSRead. There are other verbs and other conventions to map to that. So you can see that then the argument name was what I had passed in. If I didn’t pass it, it just uses world, otherwise it substitutes that in and it returns a message. That message is automatically serialized back as JSON for the response. So pretty easy to set this up. Literally, all you have to do is make this resource this form and you can run with it. Some other things that I’d like to recap is just some best practices or typical capabilities. So I’m going to request another endpoint orders. And you can see that the response is a list of order records. You can also see that there’s a page number here and if I go down, you can see the page size is 10. So a bit of pagination available there, we can request multiple pages, we can even change the page size. So, and I believe that is, let’s just make it smaller. So now you can see, I didn’t do my parameter right. But let me take you under the hood and look it at that get and then we’ll get the right parameter for the page size. So I’m going to my my orders form and you can see that the WS read here is actually implemented in a base form API base. So I used a bit of form inheritance to extend that and then pretty much this has default logic that I’m using for any of those endpoints. So if I did orders or customers or products, it’s actually going to just run through this and I didn’t write any specific logic around orders. And it’s, it’s just returning all the fields that it can for that particular database table. If I look for the page page size with an underscore, so there you go. So now you can see that I’ve, I limit the page size to one. It will change it. I can also let’s put the page back to whatever the default was. I think it was 10, but we’ll go to page two and you can see that that is on page two here and the results would be the next batch in that list. Some other things that we can do, we could let’s do a different table just for fun. We could do customers. And well, let’s take two orders because I actually know an order ID off the top of my head or in my history. So orders and I put in an order ID. So instead of getting a list, I’ve requested a specific order by ID. Some other things we can do is we could we could ask to include a bit of related information. So I’m asking for in this case the order details. And you can see that in addition to the the regular fields it has here in array of the details in there. None of the functionality I’m showing you is necessarily required or even you know out of the box. It’s quite easy to do. But these are some common conventions in a web service and I just wanted to show you that it’s possible and easy to do and a little bit how it was done. Again, this is a bit of a recap. This is not new stuff. I mean, get to the new stuff in a minute. Some other things you might want to do is to well, we can add related information about the customer as well. So now you can see here’s the customer info down here. Let’s go back to our list and let’s specify that we just want to limit the fields and we want an ownership country. And maybe ship city. So now you can see that I’m limiting the fields. And maybe I also want to add a filter and I want where ship country equals Germany. But I’ll still limit my fields with that parameter. As now you can see that all of the orders here are German orders. But the fields are still limited. So just being able to allow your API users the flexibility to request records in the way that they want. Maybe we want to also do sort equals ship city. Believe that’s how you do it. And now you can see that the city’s beginning with A are first and going now in order down alphabetically. I think invert it with a minus. And now you can see that it’s going in reverse order starting with Stuethcart. So again, this was all stuff that I had demoed in the long ago webinar, not none of this is yet brand new. What I do want to point out though is that everything that was passed in was really in the arguments there. The first one is the ID and then there’s the query string and then I’m just sort of parsing the query string here. And this is a utility method I wrote in a base form. So any of these endpoints that I set up without writing any additional code will implement some of the pagination and the filtering and the sorting and restricting the fields including related records, etc. So again, I think I don’t want to go too deep into how this was done because there’s new stuff to show with 2019 and that’s what this webinar is all about. So what I’d like to do is come back here and show you version two of the Hello World. So I’m going to go back to my Hello World example and I’m going to stick a V2 in front of the Hello World in my URL. Oh, this one wants a, I’ll put my name there, wants a name. Okay, so now you can see it says Hello Sean, welcome to version two. Let me take you under the hood and show you how that was supported because this is, this is new. And there’s actually two things that I’m going to show you that are new here. So first of all, you’ll notice that I’ve implemented a few scopes including Hello World V2 and a WS read method in there. And this is where that was implemented. So nothing different except for two things. Number one, scopes are now supported. The rest plugin has been in Servoy since a way long ago, even before we had what we call these top level scopes. So everything was sort of segmented by form and that’s how you map the resource. Also nice because forms already had a dedicated found set. So made loading a bit simpler also form support inheritance. You can do things like what I did where I put everything in API base and all the other endpoints sort of inherited that functionality. So I’m not saying that that forms are old and scopes are new and you should use scopes. I’m saying now you have the flexibility and if you have some non some different stuff that you want to implement in scopes, you’re free to do so and you can mix it up. So what I did here is I implemented Hello World underscore V2 as a scope and the rest plugin is smart enough to recognize the V2 and if you you can call it what you want but it’ll sort of find that in the URL and look for something that has that appended to the end of the resource. So that’s how I get Hello World V2 in this example. I want to do another example here. This time we’ll do orders V2 and I want to do adding an endpoint that goes a little bit deeper. So I already showed you how we can get orders. We could also do a version two of that but let’s say I want to add an item to two in order. In this case I’m going to add it to order 10249 and I want to add a new product and specify the so I’m calling add item this time it’s not just a poster or get but it’s also doing some specific method. So I’m going to send that and you can see that it returns the response and in there it has the the order details or the line items for this order and you can see product 50 there has a quantity 40 it’s because it already had 30 when I started so I’m going to call this one more time and you should see it should go up by another 10. So a bit of arbitrary business logic but just to show the show so there you go product ID 50 now quantity 50 I could change the payload here and make the quantity 100 and now it should go up by another 100. So now you can see the quantity is 150. So you get the idea but what I want you to understand about this is that this add item section of the URL is now seen not necessarily as an argument but as a as a route to a method under that specific resource and we added this because this is a common rest convention you go you have sort of these mapped resources like customers orders these entities in your in your system and then you maybe want to do the typical crud stuff which is you know post and put and and get in terms of HTTP verbs but you also might have custom stuff that goes beyond that in this case like adding an item to an order and you want to express that as a separate method. So let’s look at the method that was implemented again this time I put orders V2 as a scope I could have done it as a form I could do it as a form that inherits from orders base here or version one but in this case I did as a scope to show you can do this top level scopes and then I have this method Ws create and then underscore add item so again it’s looking at the URL the rest plugin is smart enough to know that add item appears under one of the rest handler methods for that resource and it routes it that way and what it does it it’s I mean any of the puts or posts will always put the payload the the body of the request is the first argument and then if you’re routing this to a method it will actually pass the method name in as another argument in most cases you can just ignore that and then finally it’s whatever arguments or query stream come after that in this case it was just the order ID so I just find the the order that I’m looking for and if it already exists I just locate it otherwise I’m adding that line item and then I increment the quantity so that’s that’s why the first time it’ll actually add the line item the next time it’ll just keep incrementing the quantity and then what I’m doing is I’m call just for the sake of the example I’m calling down here the first version of this to just serialize the response back that that record back because that didn’t really change but what I really wanted to point out here is that this method signatures custom add item and that is a new URL path there so that’s kind of what’s new so far in terms of the rest plug-in functionality it’s those three things scopes versions and deeper endpoints and I think that’s a satisfactory example I wanted to leave time to show you another anything we’re working on which is a documentation generator for this what I’m going to do is activate another solution that I have here called SUI example API and this is a much sort of simpler example and you can see that it has two endpoints it has a store and a pet so this is a pet store sort of example and you can see that store has a WS create for handling posts and a read inventory which is one of those mapped methods and then it also has a form for the pet itself and quite some rest methods there let’s just jump into one of these and look at some of the tags that are here for example the read object or the read method has some documentation and it has these tags in it the summary the parameter the different return types you may notice that there’s an enum tag here you may notice a deprecated tag here on the find by name so what we’ve done is a colleague of mine made a a needs module that he was working on with the customer that’s already in production with this documentation generator and they wanted to be able to use a tool called swagger UI to visualize and test their API I’m going to reload this page here so you’ll notice the URL here is the same endpoint as what would be how I request except that it goes to the swagger.json which is like a descriptor and then what it does is it runs this module that is able to go in and parse or read those WS underscore methods as well as the the endpoints where they exist so those scopes and those forms and it’s able to generate out the documentation so you can see here that pet was a form and it had those different you know WS create WS update WS read and WS delete methods get converted into these HTTP verbs you’ll notice that the description like add a new pet to the store if I go back to the WS create method of method you’ll see the summary tag here add a new pet to the store I could put in and add a brand new pet to the store and save that and if I were to come back here and and refresh the documentation you can see that the summary summary there add a brand new pet to the store was updated so it’s live whatever is in source it’s just being generated from that this wasn’t pre-compiled or anything like that you can see that this one here shows is deprecated find pets by tag and you can see that uh I have find pets by name I mean you can see the deprecated tag right here and that will render it as such you could probably add another message here like use something else and if I come back in to this I think it I thought I would put that in there while I went off script this is a work in progress so we’re getting the module here a little bit refined but these key tags are supported finally what I want to point out is that one enum tag if you look at the top of this we have this enum tag on this status and farther down you can see for example read find by status one of those custom endpoints it specifies that it takes an array of those enum objects and if I were to come back here to the generated documentation and find by status you can see that there is one of these list boxes here that show you how to do it and what’s an acceptable value to pass this tool swagger UI you can even test out your endpoints so I’m going to click try it out and I’m going to execute and you can see that it didn’t like that I didn’t supply this because it’s marked as required so I’ll put in pending and I’ll put execute and it gives some information about you know what was sent you can see the response was handled code 200 here’s the response body here’s all the headers so not only does this automatically generate documentation for this particular tool this tool is also a testing tool so you could you could set up a sort of sandbox account point the documentation generator to it and then release this to your customers and they could actually go and read the documentation and try it out so it’s quite it’s quite useful again here you could do find by ID try it out I don’t know the ID so I probably get well I got lucky I found one with ID one good guess but you get the idea so if you’re not familiar with this tool you can read up on swagger UI but it generates in this for you there is a project on github that we just released called SUI API this is released if you look at the release notes this is released in beta because we are still working there’s a few issues we’re adding support for versioning we do have support for those top level scopes and we do have support for those deeper endpoints that I showed you that are new but working on support for versioning we’re also working on a couple of issues with warnings that get generated so we’re leaving this as sort of a pre-release for now but it is now available through the web package manager so all you have to do is you can see that there’s the SUI API example solution here it includes this SVY helper module and you can add that to your own project by running our package manager and you pick uh Servoy solutions or modules and you can see it’s right up there SVY API and you just click the plus and you can add it to your application now there’s a few more steps you have to take but it’s really quite easy and if you go to the wiki page of this project and click the getting started it’ll tell you how to basically have to download the swagger UI and put it out on your web server that just takes a minute or two and then there’s one file where you have to change one line to map it to your particular application and then it will go and generate the documentation for you so that’s the demo of the doc generator let’s just do a quick recap of what we saw so just for those of you who are brand new to web services and Servoy this ships by default nothing to install no extensions you need to worry about it just launches a server side client to handle requests as soon as there it doesn’t on a lazy load so as soon as you first request an endpoint it launches it and it’s running simple naming convention to map resources to HTTP verbs you can do whatever you want in those but what I tried to show you were some common conventions and the example solution that I was running is available we posted that a while ago when I did this webinar before and it has a nice sort of helper base form that you can do all the stuff that I showed you on any any resource so you can do list detail you can do pagination you can include related records you can choose which field to want to return you can also sort the results you can add filters I didn’t cover authentication but there’s a couple of authentication schemes authentication was covered in the prior webinar more extenServoy I want to get to what’s new so first of all we add a support for scope for scopes so either a form or a scope is then exposed as a map resource in your in your URL convention and depending on the HTTP verb that gets called it it will call one of those those methods that you define those Ws underscore methods and you can see here which verbs they map to that hasn’t changed however you can add versioning now to your API and if you sort of stick that version number in there it’s kind of smart you can put it in at the very beginning you can put it in right before the resource and the plug-in is able to figure it out and what it does is it looks for that that form or that scope and it looks for an underscore with that version tag and and tries to locate it that way something else that was new that we saw you can actually add a customized endpoint that maps to a specific method so not just the create read update delete but also a specific method of your choice it still has that Ws underscore prefix it also needs the name of the verb that will get called so create read update delete because we need to know how to handle the rest verb or the HTTP verb but then you can add underscore whatever you want and and it’ll map that URL to your method so you can get into some more custom stuff finally what I showed you was a doc generator tool this is now an extension so everything that I showed you up until that point is part of Servoy core you can do that today without installing anything extra but this is a a new extension project that we started it generates documentation automatically right from your source code and it uses a tool called swagger UI which allows you to visualize and test that one thing that’s neat about that it’s generating directly from source code is that it’s always up to date so the same code you used to document your you know your code this the same tags and the same conventions it will it will just read those and generate the documentation for you so if you go and you put out something new on your on your application server your documentation is automatically up to date because it’s done dynamically and again this is really easy to set up you just include that module it’s available in the package manager you have to download the swagger UI stuff and also put it on your web server and then you just configure there’s a index HTML file and get into the details of that but the instructions are there on the wiki just modify one URL and a little file and it points into your web service to generate documentation for so i hope that you found the new stuff compelling oh sorry a quick list of some of the tags that are supported i think most notable are those e-noms and the deprecated tags anyway i’m going to leave up information about Servoy world it’s going to be a lot of fun we have a hackathon i think we’ve been hammering you guys with this so i’m i’m not going to get into it but i’ll leave up the details here well we take some questions because i see some are coming in and i’m actually one started asking a question about version link but you answered it a little bit further down the road so there was there was done just good and Bob q6 says that’s really helpful adding in points with in to entities with a naming convention so it’s just a complementer shanjade and looks like everybody else is either very quiet or they really agree with everything that you have said today it’s unlike the last webinar we had 30 minutes of questions so okay well i wanted to also announce that i’ll leave up these useful links for a minute and show you there’s the the URL for the scyapi project although you can get it through the package manager also links for how you could download links for signing up for Servoy world i think there’s still some rooms available at the movin pic and also links for how to watch a recording of this webinar or maybe you want to watch the older webinar about the sort of complete webinar about web services which is still completely relevant