The Istanbul release introduces some very exciting features for APIs and Authentication. This post will bring you up to speed on what’s new, and we’ll follow up with more detailed posts about individual features in the coming days/weeks.
New Inbound OAuth 2.0 Features
Have you ever tried to build an app that integrates with ServiceNow, only to find that you couldn’t issue API calls on behalf of a specific user unless that user had credentials stored locally in the instance? Istanbul introduces several new inbound OAuth flows to address this.
Authorization Code Grant Flow
If you’ve ever used an app on your smartphone that asks for access to your Google, Facebook, Dropbox or similar service, you’ve probably seen Authorization Code Grant Flow in action. This OAuth flow redirects the end user from your app to the ServiceNow UI to authenticate/authorize access, and then redirects the user back to your app. This allows you to generate Access Tokens on behalf of a user, even if your organization uses SAML or some other form of SSO. This also means it is no longer necessary to limit inbound API calls to a centralized Service Account.
Implicit Grant Flow
It’s now much easier to find and manage OAuth tokens. As an administrator, navigate to System OAuth > Manage Tokens, and you can manage tokens here.
End users can also manage their own tokens from Self-Service -> My Connected Apps and can easily revoke specific tokens if desired.
Changes to RESTMessageV2
There are a several notable changes to outbound REST Message functionality.
REST Messages can now have more than one HTTP Method of each type
For example, a REST Message can be configured with multiple “GET” methods, each with its own parameters. This makes REST Message definitions more flexible and allows you to consolidate similar calls under a single message.
Other noteworthy changes:
- When you create a new REST Message, only a default GET REST Method is generated. PUT/POST/DELETE methods are not automatically generated, but can easily be created if you need them.
- REST Messages now support the PATCH method.
Outbound HTTP Request Logging
Outbound request logging keeps track of the HTTP requests made by code in your ServiceNow instance. REST and SOAP requests, and outbound requests made by GlideHTTPRequest/GlideHTTPClient will be logged.
This functionality provides numerous benefits:
- Simplified debugging for developers
- Easier troubleshooting for administrators
- Cleaner code (reduces debugging/logging statements)
- Auditing of what external systems your instance is talking to
Outbound logging can be optionally configured to log request headers, request body, query parameters, response headers and response body when additional detail is needed.
Outbound HTTP Log Detail
For more information, see Outbound Web Services Logging in Detail.
New Email API
Istanbul introduces a RESTful Email API that simplifies the process of sending basic notifications from your apps. Sending an email is as simple as POSTing a JSON body to the Email API endpoint.
B “to”: [
B B B “Josh Nerius <firstname.lastname@example.org>“,
B B B B “Dave Slusher <email@example.com>”
B “subject”: “Test from the new Istanbul Email API!”,
B “text”: “This is pretty cool stuff”,
B B “table_name”: “incident”,
B B “table_record_id”: “d71f7935c0a8016700802b64c67c11c6”
This will build an outbound Email associated with the specified record:
Requestor Tracking in API Analytics
API Analytics has been enhanced to track which users make requests to APIs. This will give developers and administrators valuable information about who is using APIs in the platform.