6 minute read
One of the new features in Geneva is the ability to write Scripted REST APIs. These take the place where Processors were used previously but have a richer feature set and more flexibility.
Scripted Rest API basics
When you create a new API inside the Studio environment, you define a name for it and an API ID (which will default to the name but can vary independently). Based on your currently selected application scope, it will automatically choose that application and namespace which corresponds to your scope identifier. Finally, you can set a protection policy to use no protection, make it read-only or protected.
After saving or submitting, you will see the Base API path that was created for you. This will be /api/<APPLICATION_SCOPE>/<API_ID>/ . That will be the prefix for all the individual resources you create, so if you create resource “foo”, your fully qualified URL would be:
https://instancename.service-now.com/api/<APPLICATION_SCOPE>/<API_ID>/foo
Upon creating a new resource, you will be asked for the name of the resource, the HTTP method or verb used to access it, and the relative path.B The relative path can be arbitrarily complex and as in this screenshot, can contain multiple levels of path. You are not limited to a single level.
In addition, you can define path parameters as part of this relative path. Any parameter defined as part of the path as in the example will then be available to the scripting environment. The bracketed text will become a variable that is available from the request.pathParams object. More on this later.
Verbs
As you would expect in any modern API, you can support any of the HTTP verbs for any resource you define. This allows you to use the style of a single endpoint with multiple verbs where
GET /item/{id}
would be used to get the read view for a single data item while
PUT /item/{id}
would be used to update it and
DELETE /item/{id}
would then remove the item from the database. This allows you to create a simple externally facing interface that conforms to the style that other systems expect.
Scripting
Associated with every resource is a scripting window. This is where the work of Scripted REST APIs really happens. The context of the script window provides a request and response object. As part of the Geneva enhancements you will be able to see all the methods available on these objects using the autocomplete functionality.
The main functionality provided by the request object is the hashes for pathParams and queryParams. In the example above where the resource is defined with an {id} template for the path parameter, that is accessed in scripting by
B B B B var id = request.pathParams.id;
or alternately (both syntaxes work)
B B B var id = request.pathParams[‘id’];
The same thing can be done for query parameters, so that if the resource was called with a query string of “?maxRecords=30”, it would be available to the script by
B B B var id = request.queryParams.maxRecords;
The response object allows for low level control of the return, including manipulating headers, status codes, and the stream writer of the response itself. It is not necessary to use it, if a JSON object is returned by the process(request, response) function then that will be the output, defined as “results” similarly to the default behavior of GlideAjax.
Inside this scripting environment, you have full control over the system up to the limits of the scope, with access to GlideRecord, GlideSystem and the functionality you would expect in a scripting environment. This allows you to within a scoped application expose any functionality that the scope can access through the system. For example, it would be possible to create a scoped application called “IncidentPlus” that provided a full logical API for interacting with Incident records on the core system. Although the scoped application would own the REST API endpoints, the functionality can be anything allowed in that scope and does not need to be confined to records within that scope.
Rest API Explorer
Once the endpoints are defined, the REST API Explorer on your instance can be used to interact with and test your API. It works exactly the same for your custom defined endpoints as it does for system provided APIs like the Table API. You will be presented with an interface to pick the Namespace, the API, the version and which resource to access. If the endpoint has path parameters defined there will be fields to enter those, and also the ability to add arbitrary query parameters to the request. Additionally, you can manipulate the headers such as the request and response data formats, and as well can add arbitrary headers if you desire.
Sending the request will then display the return value. If you did everything correctly, you will see a status of 200 and the data you expected. If debugging, you might commonly experience a 500 error and some error messaging. You can use the REST API Explorer as a debugging tool to exercise your API until you get the logic correctly working.
Versioning
Versioning was briefly mentioned above. Scripted REST APIs support versioning, which is also a best practice of using them. This allows for adding, deprecating or altering behavior of the API in a subsequent version while leaving the original API with original behavior operational as a previous version. This way current users of the API can be protected from changes. If your request uses a version qualified endpoint, then it will not accidentally be using functionality that was not intended.
This implies that when publishing an API version that behavior be held consistent within that version. Any change that would break the logic of consumers of the API should always be contained in a subsequent version to minimize disruption to any deployed accessors to your API. When publishing your APIs, publishing the versioned form of it allows consumer to “pin” their implementation to your version of the API, again isolating the consumer from any future changes.
Summary
Scripted REST APIs present a powerful tool to developers. They allow users to define logical level APIS, with little or no implementation details required to use them and arbitrary scripting to deliver the resources. This enables more robust, less brittle integrations with external systems and less time spent maintaining this connection.
If you have interesting ideaB for (or even deployed) REST APIs, please leave them as a comment on this post. These are an exciting addition to the toolkit that really have no upper limit to the value they can enable. I am personally looking very forward to seeing the work that happens out in the world with Scripted REST APIs so let me know how you are using them.
For more information you can look at the Documentation site and also watch the episode of TechNow in which I did a demonstration of some of the capabilities of Scripted REST APIs. Happy exploring!
Share this post
Twitter
Facebook
Reddit
LinkedIn
Email