Scripted REST APIs in ServiceNow
Updated: Nov 17, 2022
With Sheikh Kamarah
In this article, you will learn about scripted REST APIs in ServiceNow. What we have in our PDI is the scripted REST API table. A scripted REST API is a web service that one can build and configure to allow external systems to talk to ServiceNow.
Why use Scripted REST APIs in ServiceNow?
Why would you want to use scripted REST APIs in ServiceNow? For one, you may not have access to the Integration Hub. There may come a time when the import sets or data sources provided to ServiceNow, or even the endpoints directly to the tables, are not robust enough or give too much access. If you want to do something you have more control over, a scripted REST API is perfect for that.
For example, if you come across webhooks and want to subscribe to events in an external system to generate tickets of some sort. If you want to incorporate that webhook into ServiceNow, scripted REST API is perfect. You can process the JSON package or payload however you would like, or if you're dealing with some funky authentication, you can handle it through scripting; It’s very versatile. There are also instances where maybe you don't want to give important information or access to the entire table to an external system, so you may want to curate the type of response that they're getting. With inbound web services, for example, the response you get once you use that API is not extremely robust, so maybe you want to give more information, or it's a GET function, and you want to pass back certain fields and not give the whole table access.
There are multiple reasons you may want to use a scripted REST API, but mainly what we would use it for is when you need ultimate flexibility, or you need to really tailor the response. In today’s example, we have an external system that our managers use, and every time somebody requests software, they go in and check the reports to see if it's available in the first place. Behind the scenes, the portal will tap into ServiceNow to check if the model exists, if an entitlement exists for it, and if one does exist, it will see if there are allocations available, and then it reports that number back.
Building an API
Let's go ahead and build that API; to start, we will click the New button. We're going to name it Entitlement Allocations; the API ID is auto-populated based on the name, but you can change that if desired. The API namespace is also auto-populated; this is derived from a property because the application is global. If it were any other scoped application, the API namespace for that scope application would show in the API namespace.
We are going to save this, and now you can see that the API ID and the API namespace are both incorporated into the Base API path. The Base API path is the endpoint that we're going to provide to external systems, but we need to add more to this endpoint in terms of specific resources that the endpoint can use to get information from ServiceNow.
Creating a Resource
Let's go ahead and create a resource. We start by scrolling down to the Resources tab and clicking on the New button. We want to give it a unique name because you could create as many resources as you want for your API; in this case, we’ll name it getAllocations. For the HTTP method, we are going to select GET. We will fill out the rest of the endpoint path, the relative path. When you call this endpoint, we want to call getAllocations, and also you want to pass in a variable, which will be the model name that we'll be looking up (reference video at 3:46).
Writing the Script
Now it’s time to write the script that will process either a payload or just the request from the GET call., Down at the bottom, we have some security, so if you want to enforce authentication and the ACLs, you can use the two checkboxes. We don't recommend unchecking these unless you plan to handle them in the script above. If you leave these unchecked, then the endpoint is wide open to the internet, and that is not a good idea, so please leave these checked unless you plan to handle that in the script.
Please reference the video at 4:40 - 7:58 to view the script being written.
To write this script, the first thing to do is get the model, and we get that by using the request object. There's also a response object you will see. We will get the pathParams, and then it will call model. We are going to check if anything was sent, and if not, we will go ahead and return an error.
We will use the response object to set an error. This is one of ServiceNow's handy little error objects that they provide to you. We are going to use a not found error to provide our message, “no model found in the URL”. We are now going to set our status to 404 and return. That will be the end of the script if no model is sent. If you do have a model, then we'll go ahead and query the entitlements table.
We’re going to add a simple query to see if the software model associated with this entitlement has the same name as the name that was sent in. We're going to be looking at the display name, and we'll query that. If there are no entitlements at all, then we're going to return an error, and it's going to be just like the other one we did, except let's use a more specific error saying “no entitlement”. If we do find entitlement or more, let's get a count going. Let's make sure we get a positive response here. Let's also set the body to a JSON object where we return the count. And our script is complete.
Testing the Script
Let's go ahead and test our script in the Rest API Explorer. If you scroll down to ExploreRest API, it will take us to the endpoint that we just created; this would be the endpoint that you would provide to the external system. Under Prepare request, we will set the value as Adobe Systems Photoshop CC 2017. Let’s hit the Send button to test that out. If the response takes a while, go back to your script and make sure everything is correct. For our example, we have a quick change we need to make and make sure we save it (reference video at 8:34). Now that it’s saved, let's go ahead and try that again. Now looking under our Response tab, we see we got a 200 response. We get a count and a message of success. If we were to enter something that's not in the system and hit Send, we would get our 404 Not Found message. In this case, we didn't get that message, which means everything is properly set up.
Did you find this introduction to Scripted REST APIs ServiceNow article helpful? Are you ready to start your journey with ServiceNow? If you want to find out more information about GlideFast Consulting and our ServiceNow implementation services, you can reach out to us here.
About GlideFast Consulting
GlideFast is a ServiceNow Elite Partner and professional services firm that provides tailored solutions and professional services for ServiceNow implementations, integrations, managed support services, application development, and training. Reach out to our team here.