I am sure most of you guys might be aware of it already, however, I would like to share my experience while working on Scripted REST APIs. Scripted REST APIs are a powerful way to create custom endpoints for your ServiceNow applications, and to expose data and functionality to external systems. They are also easy to create and maintain.
Before we proceed further, it is important to understand when to choose scripted REST APIs. We need to know if we are not recreating something which is already available, we need to make sure that we are not complicating a simpler solution.
When to choose or go with Scripted REST APIs
There can be many reasons to it for e.g., security: where you don’t want an external system to have full access to your table, flexibility for the payload, fancy authentications, more restrictions, scripting to communicate between tables or reusable methods over different API resources, etc. In my case there were two strong reasons to not choose table APIs:
- My organization does not want the table APIs to be directly available due to security reasons as it is hard to track who and how many times the table APIs have been accessed and it can even spoil your ServiceNow data if accessed wrongly.
- The requirements were to get custom payload which could not be possible with table APIs.
Now that we are clear when to choose scripted REST APIs, lets deep dive into the good practices for it.
- Authentication: Avoid basic authentication and go for OAuth wherever possible. OAuth is more secure and advanced to authenticate. In this article I will not be explaining what OAuth is, but below links can help you understand about it and how to set it up for your APIs. https://www.servicenow.com/docs/bundle/yokohama-platform-security/page/administer/security/concept/c...
https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB0778194 - Once you are done with setting up OAuth profile, make sure you enforce it, so that nobody can get access your APIs with the help of basic authentication. In order to achieve this, you need to setup REST API access policies.
- Authorization: Now that you have been authenticated, next step should be authorization, this can be achieved with the help of ACLs. You need to perform two major changes:
- Remove the default ACL (Scripted REST External Default) selected in your scripted API resources and create a new ACL of type REST_Endpoint and add it to your resource. The default ACL contains snc_internal role which exposes your API to all the users in your organization.
- Use GlideRecordSecure in place of GlideRecord to enforce the table level ACLs to your APIs. This will validate if the user is having access to read/write/create/delete on your table or not.
- Follow REST API conventions: Use the appropriate conventions for specific usage. GET should only be used to query data/read data and not for any other purpose. POST must create records, PUT and PATCH to modify existing records, DELETE to delete records.
- Versioning: Once we have secured our APIs we can move on to the next and very important part which is called versioning. This is one of the best features as it helps in creating multiple different versions of same API resource (as per the modifications in the requirements) without breaking the existing integration. We can have multiple active versions of our API, and all can be accessed just by appending version in the API resource URL. To utilize it more properly we should configure the API without a default version which will force the API consumers to specify a version in their request and get the appropriate response.
- Informative HTTP status code and error messages: Return the appropriate HTTP status code to help the consumers understand the success or failure of the request. In case of failure, return appropriate error message/information along with your error code which allows the client to understand the problem without having to refer the API documentation.
- Documentation: This is one of the most important parts of your development. A good documentation is equivalent to the best development. Once an API is published, API documentation makes sure another party (both internally and externally) knows what it can be used for and how it should be used.
Consider an example, you purchased Wireless headphones /Airdopes (wireless earbuds) and it came without a manual, how much difficult it will be for you to understand its functionalities like: how many times to tap on the earbud to go forward or backward in your music library, how to pick a call, how to access AI assistant and many more. Just like this, documentation helps you understand how and what to access in this API. - Test cases: Create your test cases to verify if you are getting the desired result. You should get the correct response status code, you should get appropriate message/information, you should get the payload in the desired format, you should receive correct error code etc. You can use postman, ATFs or any other REST client application that supports automated testing.
Note: To increase the security or restriction a bit more you can use authentication scopes. In below mentioned video series you can read about it more.
Below are some useful links which can help you understand and learn Scripted REST APIs in ServiceNow.
YouTube series on Scripted REST APIs
Scripted REST APIs in ServiceNow
Hit the helpful button if you liked it or found it helpful. Bookmark it for further updates!
Regards,
Mohit Kaushik
Developer and Community MVP 2023
