Josh Nerius

4 minute read

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

Istanbul_OAuth_Auth_Screenshot.png

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

Implicit Grant Flow is also supported starting with Istanbul. This flow is most commonly used when building single page client-side JavaScript applications that need to communicate directly with ServiceNow APIs without a server-side component to handle token exchange.

Manage Tokens

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.

Istanbul_OAuth_Manage_Tokens.png

End users can also manage their own tokens from Self-Service -> My Connected Apps and can easily revoke specific tokens if desired.

Istanbul_OAuth_Revoke_Tokens.png

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.

Istanbul_RMv2_HTTP_Method_List.png

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.

Istanbul_Outbound_HTTP_Request_Module.png

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

Istanbul_Outbound_HTTP_Log_Detail_Page.png

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.

Example

POST /api/now/v1/email

{

B “to”: [

B B B “Josh Nerius <josh.nerius@servicenow.com>“,

B B B B “Dave Slusher <dave.slusher@servicenow.com>”

B ],

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:

Istanbul_Email_API_Result.png

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.

Istanbul_API_Analytics_By_Requestor.png

Additional Istanbul Resources


Comments