Learn JavaScript on the Now Platform: Lesson 36 - Scripted REST APIs

welcome to lesson 36 congratulations we're nearly at the end we're going to take everything we've learned about JavaScript and apply it to something in ServiceNow called a scripted REST API this is a way for other systems to interact with ServiceNow where you have total control of what gets accepted the payload the format how it's processed and what gets returned as a response so rest stands for representational state transfer it's a way to transmit and exchange information over the internet with another system a common use case that I cited before was let's go get a stock price or let's check the uber status or let's make a playlist in Spotify there are lots of REST API is out there all you need are credentials the endpoint and understand what is the structure of what I need to present so we're going to make one on ServiceNow that somebody could potentially interact with to extend the example we had before where we're making a list of objects in an array of table record display values and societies so that's our end goal of what we're going to do so before we get into that I need to show you a few things about what REST API czar and how they're constructed you'll find them underneath script addressed api's and there they are on dursa system web services script addressed api's and when we create a new one we're going to give this a name so let's call this record finder and the API will be record underscore finder that's automatically assigned but you can change that if you like I'm going to go ahead and save that we don't need to worry about any of the other fields for the security we'll use default ACLs content negotiation we don't need to worry about any of that let's go down here to the resources this is where we're going to define specific functionality we're going to use a new resource so let's create that and give it a name get table records it's going to be a get now we have different ways to interact with the system get says hey service now I would like to get information I'm going to provide you with possibly some parameters and we'll look at those in a second and you're going to send me information this is just what Finance now yahoo.com does when you say I want to get a stock price it has a public-facing web service may or may not require authentication and return some information to us a post is when I want to create a new record so if I send a payload I want to create a new incident in ServiceNow I could do that and there are lots of existing REST API s that we can do that but we're not going to do a post put and patch our way to update an existing record I'm not going to get into the nuances of the differences of those today and then obviously delete allows you to delete a record so we're going to set up a method for users to get information from ServiceNow the relative path is if I had multiple things on the record underscore finder API I could have one that says list for example this would be the full name of my API at this point it would be record underscore finder slash list I could have one that creates I could have one that updates but since I don't expect to have any more I'm just going to leave that as slash now down here is the scripted portion of my scripted REST API note it's enclosed in a function we should be familiar with that it has some parameters that it's automatically giving it to us request and response and those are fully documented on the docs site and it also has requests in a response down here that I that that's how we interact with the scripted REST API through those objects those are predefined so avoid naming your variables request and response and down here is where we have our code now the first example I've got looks like this I'm simply going to do a hello world I'm going to return a value and when I save that I'm not going to run that in scripts background this is now available as a web service in fact you know what let's give this a relative path thing because I am going to have more than one this is going to be lesson 36 script 1 save that so I have a full path this is the resource path to my API so if I want to hit this I would do HTTP slash slash instance name dot ServiceNow comm slash API slash six six two three eight blah blah blah blah blah all right and I should get a hello world now we also have a very nice tool for interacting with this called the REST API Explorer this allows you to test this out if a third-party application was to interact with ServiceNow we can use the REST API Explorer to test it out make sure the headers are right even give them code snippets for Perl and Python and possibly some other ones so by clicking that REST API Explorer it takes me right to this endpoint and it says hey Chuck this is how you're going to interact with it and there's some other options on here which we'll get to in a bit the different resources are listed here I only have the one so that's what I get and down here is where I send this request and it comes back it says if is you this get to this end point with these default headers I get a 200 which is okay we like to hundreds and this is your response it took 180 millisecond 86 milliseconds you've got some other information in here but down here is the response body and this is what a third-party application would be interacting with they send a request they get a response and I see result hello world hooray I've got a way of doing this I mentioned code snippets up here if I want a curl command I could do that and click that and it would say here's how you do this from the command line obviously I would need to provide some credentials if you want to do this in Python here's some Python code to get you started same kind of thing you can copy and paste and give this to your third-party developer and say here we are have fun with it get started you can now interact with ServiceNow I am on my way to creating a scripted REST API actually I've already created a scripted REST API so let's go to a little more complex I'm gonna leave the REST API Explorer up there because I'll come back and test it I'm going to make a slightly more complex script this time I'll go back to my API definition and create a new resource so that one is LS 3601 let's create another one kit table records do I didn't actually get table records yet this one is I'm working up to getting the table records that's cookie that could be our lab exercise if you're not careful this allows us to get some parameters now I am going to paste this into the function and notice all I did is add these three lines of code really the the other one is just constructing a string you should recognize that request is one of these input parameters that I've got for free request has an object and it called query params now a query parameter is something you put in the URL to specify something to the REST API in our case we want to specify is it active and what is the name so I need to publish this when I tell people about my API I need to let them know that they have to put this on the URL somewhere question mark which denotes the API from the parameters active equals true and name equals now so if I save that with a new lesson 36 script to I'm going to submit that my API becomes oh look me back to the other record let's go back in here I'll rename this as script to it'll be easier to keep track of for me save that so I stay on the record and I get back into the REST API Explorer didn't you kill Don now I've got two methods in here I'm like get table records and script two here is where I add query parameters this is where I can say what was it active is true and add another one name is now as an example I can pass this information all this script is doing is echoing that back to me so if you remember right my script wasn't that fancy it just said go get the active value go get the name value I could have done these as request query parameter request query parameter break them down like I did with my arrays and a list of objects so that I have a little less typing in this case it doesn't look like a little less typing but it could be so I'm using an object within an object to stop typing requests all the time then create a string answer that just says this is what I got back for these variables and return answer let's try it out I've specified my query parameters notice that doesn't say anything on the URL that's exactly the same except for the end point instead of SL 1 it's now so2 so I know my two different end points apart I send that and I get another ok we like ok here is the URL the fully defined URL has the question mark in it that's the nice thing about REST API Explorer if I look at the curl command it will be the same kind of thing so2 active equals true name equals now right so we see that that URL is fully constructed and the result is hey this is what I saw what you sent me is being echoed back just testing out how can I pass information eat to a scripted REST API that becomes part of the function that I can process and how can I return it out let's get a little more sophisticated now let's go on to the next example come back to this record and while I'm at it let's rename this script one there now everything's in order in the next example I'm not going to use query parameters I'm going to use path parameters slightly different so instead of instance at ServiceNow comm bah blah blah question mark it puts on a slash it's part of the path these are a little trickier and I don't use them all that often but you will see these in things like the table API for ServiceNow so if I go back to creating a resource let's call this script 3 now that we've got some order going on here and less than 36 script 3 do a get copy and paste this over how do I access those path parameters well I use instead of query params I use path params and I can pull out the table name and the ID note there they are it's got to be in this order here's an example my app table and my ID I could put in if we wanted to rebuild that last example this way I could put in the table name and the limit order to pass two parameters in via the path and I'm not a big fan of these because they look ambiguous but you could do this let's check this out it goes and constructs another basically an echo statement to respond back as a I got your parameters not a bad idea if you want to make sure that you're processing the path programs or the query parameter case successfully save that just a different way of getting information you could use potentially both you could specify some parameters on the query line you could specify some parameters with query parameters you can specify some parameters with the path parameters I haven't seen too many cases where they use both but it's possible try this again script 3 and our oh we don't use query parameters so never mind that we're using path parameters and guess what I don't see any path parameters because I didn't specify them in the path I need to put them up here in the relative path to say curly brace table name slash curly brace oh let's do ID okay when I put those in and save that go back to the REST API Explorer on the same page it now says oh I see those you have to fill them out it represents them as fields on this form so what does that look like let's put in a LM a set one two three four five six they are mandatory because they're part of the path if you don't have them you're not going to play this game very well we do a send and here is my URL API six six two three eight blah blah blah table name and ID are part of the path I get a two hundred okay I echo them back and say this is what I got for my table name and ID works very very well so path parameters you can use them the curl command same kind of thing it's just specifying them on the URL that you see there another way of getting information in there let's take a look at one more and this is going to be via a post so if I were posting or putting or patching I need to send that information via the body of the message so we can do that by using the body parameters so instead of creating a get this time let's do a post relative path l36 so3 for around for I believe paste that in there yes we're on for I put it in the header for you to help find it less than 36 script for the way I access the body parameters is through request dot body dot data dot whatever the name is data is an object it has name value pairs so I am expecting I'm going to copy these down just so I remember name ID and color and then I'll echo those out so let's we're building this up very very slowly save that nope forgot a name script for save that nothing else in the relative path there's my script and go down to the REST API Explorer there's a lot more to know about script address api's but I'm getting you the fundamentals so you understand how we can use some server-side script JavaScript in an application and interact with the system building your own integration thought this would be a fun way to do that so this is a post which means it's going to require a request body now in order to satisfy the API requirements I'm going to say was it named I have the answer right here name ID and color name oh let's just use mine because I have no imagination ID is 1 2 3 4 and color color is I'm feeling creative let's do an RGB value of something like that I could have formatted this wouldn't have a problem if I'd said this is the body of this thing if I wanted to make it a little easier or copying you pasting it from somewhere else maybe I've got this sample code of testing it somewhere do indentation whatever you like make it easy on yourself but to provide a decent JSON JavaScript object notation JSON payload for this and it's going to say ah this is the body data send that that's and you get a warning it says hey you might be doing something that's going to affect the instance that's fine we're not actually doing anything but you could be creating records with this here's my request body looks wonderful here's the status the response ok and it says I see your name ID and Chuck or color excuse me if I wanted to retry this and say maybe I forgot the color okay what would it do it would say it's undefined so down in my response body you didn't give me a color it's undefined so I may want some error checking in my code to say if it's undefined let's use the default of white gray green blue whatever so that's the three main methods of sending information to a scripted REST API query parameters path parameters and in the post a body but there's more hold on we want a response back so let's take a look at this script here I've got the same kind of thing name ID and color in a post I'm sending in this information and I want to give a custom response back not just echo out a one-line result I would like to send back an object of my own that has a status it has an author it has perhaps a object e in it okay and some other properties so I want to get that back so that whoever is asking this maybe it's like a stock ticker what's the price what's the name of the company what's this ticker symbol what was yesterday's high what was the weekly low that kind of thing I can send that back and I do that via response dot set body and I pass it my object not a string a fight object mind you it will take care of that there are other responses that I can set if I want to change that to hundred maybe I found an error hey I don't have a record like that you can send back a status of 404 look at the response and request objects there's a lot of great information in there on how to pull information out of the request and how to send rich information back in the response I'm being very simple in this example just as an illustration of what you can do then I'm going to return the response so let's look at how that would work those that go back make one more API open the record and create a nother new resource called script five less than 36 script 5 this is going to be a post I've forgotten that many times so don't forget if you're making a post make a post so again get my three parameters just like before these are body parameters so I expect a request body to come in do some processing here assemble my answer object set that in the body of the response and return that's good enough for me and of course I hit submit again so I gotta go back in the record sorry about that let's go down to the REST API Explorer comes up with script five is another post I should have copy and pasted instead I'll have to type that again however instead of doing raw I could do a builder and say name Chuck I could say ID yes and notice that it's putting these all in quotes so if I want ate an actual number I would have to go and modify the raw values which is easy enough color is blue in raw it doesn't have anything but what I could do is say you know what that's close you got me there Thank You field builder but ID is actually going to be a number of four five six seven okay that would be an integer value either way you can do this just understand what it is you're getting I prefer to pass in strings they're less suspect to weird things happening on the internet because remember well you can pass back and forth is text but that being said you can always tell your script address API do you have a number remember that type of if you don't have a number let's do a parse int remember that we talked about that you could do that let's send this says you're doing a post that could be volatile dangerous here's my endpoint here's my payload I got a 200 and here's my response notice that it is enclosed in a result object so if my third-party application was to do this it's always going to being a result there's no way to really take this out it's going to be whatever object they get in result dot status or result dot item dot name okay so we've got a different way to do this we can we've returned integers we can return boolean x' all of that stuff was set up for us in the script where that information comes from obviously I'm hard coding into the script you could pull that out of a record you could pull that out of a system property you could pull you could generate that live and on the fly so that is sending a response and the basics about scripted rest ap is passing information in and passing complex information out nothing in here should really catch you off guard other than the new scripted rest api constructs of creating a rest api and then creating the resources for that and obviously we had some fun exploring the rest api explorer so with that i am going to leave you with a couple of challenges to put this all together everything we've learned to date in a scripted rest api so join me for that won't you thanks for watching

Channel: ServiceNow Dev Program

Views: 12,409

Rating: 4.9786096 out of 5

Keywords:

Id: S70s5nisOjU

Length: 23min 29sec (1409 seconds)

Published: Fri Jul 12 2019