REST API Explorer

REST API Explorer in ServiceNow – Complete Guide for CAD Exam

Introduction

The REST API Explorer is one of the most important tools available in the ServiceNow platform for developers who need to interact with ServiceNow's RESTful APIs. Understanding how it works is essential not only for real-world development but also for passing the ServiceNow Certified Application Developer (CAD) exam. This guide covers everything you need to know about the REST API Explorer, including what it is, why it matters, how it works, and how to confidently answer exam questions about it.

Why Is the REST API Explorer Important?

The REST API Explorer is important for several key reasons:

1. Rapid API Development: It allows developers to quickly discover, test, and construct REST API calls without needing an external tool like Postman or cURL. This dramatically speeds up integration development.

2. Reduces Errors: By auto-generating the correct endpoint URL, request headers, query parameters, and request body, it minimizes human error when constructing API calls.

3. Built-In Documentation: It serves as a live, interactive documentation tool for all available REST APIs on the instance, including both baseline (Table API, Aggregate API, Import Set API, etc.) and custom (Scripted REST APIs) endpoints.

4. Code Generation: It generates ready-to-use code snippets in multiple languages and formats (cURL, Python, Ruby, JavaScript, Postman, etc.), making it easy to integrate ServiceNow with external systems.

5. Authentication Testing: Developers can test different authentication mechanisms directly within the explorer.

What Is the REST API Explorer?

The REST API Explorer is a built-in web-based tool within the ServiceNow platform that provides an interactive interface for exploring and testing REST APIs. It is accessible via the Application Navigator by typing REST API Explorer in the filter navigator or navigating to System Web Services > REST > REST API Explorer.

Key characteristics:
- It supports both inbound REST API calls (calls made to ServiceNow from external systems).
- It covers all standard ServiceNow REST APIs such as the Table API, Aggregate API, Import Set API, Attachment API, and Performance Analytics API.
- It also displays any Scripted REST APIs that have been created on the instance.
- It provides a graphical interface where you can select the API, the version, the HTTP method, the table or resource, and various parameters.

How Does the REST API Explorer Work?

Here is a step-by-step breakdown of how the REST API Explorer functions:

Step 1: Access the Explorer
Navigate to System Web Services > REST > REST API Explorer from the application navigator. The explorer opens in a full-page interface.

Step 2: Select the API Namespace and API
At the top of the explorer, you will see dropdown menus. The first allows you to choose the Namespace (e.g., now for baseline APIs or a custom namespace for Scripted REST APIs). The second dropdown lets you choose the specific API (e.g., Table API, Aggregate API, Import Set API).

Step 3: Select the API Version
You can select the version of the API. ServiceNow typically offers latest or specific version numbers (e.g., v1, v2). The latest option always points to the most current version.

Step 4: Choose the HTTP Method
Select the appropriate HTTP method for your operation:
- GET – Retrieve records
- POST – Create records
- PUT – Update records (full replacement)
- PATCH – Update records (partial update)
- DELETE – Delete records

Step 5: Specify the Resource Path / Table
For the Table API, you specify the table name (e.g., incident, sys_user). For other APIs, you specify the relevant resource. If performing an operation on a specific record, you also provide the sys_id.

Step 6: Set Query Parameters
You can add query parameters such as:
- sysparm_query – Encoded query string to filter results
- sysparm_fields – Comma-separated list of fields to return
- sysparm_limit – Maximum number of records to return
- sysparm_offset – Number of records to skip (for pagination)
- sysparm_display_value – Whether to return display values (true), actual values (false), or both (all)
- sysparm_exclude_reference_link – Whether to exclude reference links
- sysparm_suppress_pagination_header – Whether to suppress pagination headers

Step 7: Set Request Headers and Body
For POST, PUT, and PATCH methods, you can define the request body in JSON or XML format. Common headers like Content-Type and Accept (application/json or application/xml) can be configured.

Step 8: Send the Request
Click the Send button to execute the API call directly against your instance. The explorer will display:
- The HTTP response status code (e.g., 200 OK, 201 Created, 404 Not Found)
- The response headers
- The response body in the format you requested

Step 9: Generate Code Snippets
One of the most powerful features is the ability to generate code. The explorer provides ready-to-use code in formats such as:
- cURL
- Python
- Ruby
- JavaScript (ServiceNow)
- Postman (direct link to open in Postman)

This is extremely useful for developers who need to write integration scripts.

Key APIs Available in the REST API Explorer

1. Table API (now/table) – The most commonly used API. Allows CRUD operations on any table. This is the API most frequently referenced in CAD exam questions.

2. Aggregate API (now/stats) – Allows you to perform aggregate queries (COUNT, SUM, AVG, MIN, MAX) on table data without retrieving individual records.

3. Import Set API (now/import) – Allows you to insert data into import set tables, which then use transform maps to populate target tables.

4. Attachment API (now/attachment) – Allows you to upload, retrieve, and delete file attachments on records.

5. Scripted REST APIs – Custom APIs created by developers. These appear under their custom namespace in the explorer.

Important Concepts for the CAD Exam

- The REST API Explorer is used for inbound REST integrations (external systems calling ServiceNow). Do not confuse it with REST Messages, which are used for outbound REST calls (ServiceNow calling external systems).

- The explorer helps you build and test API requests within the ServiceNow instance. It is not an external tool.

- Scripted REST APIs created by developers will appear in the REST API Explorer automatically. They are listed under the custom application scope or namespace.

- The explorer uses the currently logged-in user's credentials for authentication when sending test requests.

- The sysparm_display_value parameter is frequently tested. When set to true, it returns the display value of reference fields and choice fields instead of the sys_id or internal value. When set to all, it returns both.

- The REST API Explorer generates the full REST endpoint URL, which follows the pattern: https://instance-name.service-now.com/api/now/table/table_name for the Table API.

Exam Tips: Answering Questions on REST API Explorer

Here are targeted tips to help you answer CAD exam questions about the REST API Explorer correctly:

1. Know the Navigation Path: Remember that the REST API Explorer is found under System Web Services > REST > REST API Explorer. Exam questions may test whether you know where to find it.

2. Inbound vs. Outbound: A very common exam trap is confusing inbound and outbound integrations. The REST API Explorer is for inbound REST calls. If a question asks about making outbound calls from ServiceNow to an external system, the answer involves REST Messages and Outbound REST Messages, NOT the REST API Explorer.

3. Know the HTTP Methods: Be able to match HTTP methods to CRUD operations. GET = Read, POST = Create, PUT/PATCH = Update, DELETE = Delete. Exam questions often present a scenario and ask which method to use.

4. Query Parameters: Pay close attention to questions about sysparm_query, sysparm_fields, sysparm_limit, and sysparm_display_value. These are the most commonly tested parameters. If a question asks how to limit the fields returned in a REST response, the answer is sysparm_fields.

5. Code Generation Feature: If a question asks about how to quickly generate a script or code to call a ServiceNow API, the REST API Explorer's code snippet generation feature is the answer.

6. Scripted REST APIs in the Explorer: Remember that Scripted REST APIs are visible in the REST API Explorer once created. If a question asks where a developer can test a Scripted REST API, the REST API Explorer is the correct answer.

7. Authentication: The REST API Explorer uses the session credentials of the logged-in user when testing. For external calls, ServiceNow REST APIs support Basic Authentication, OAuth 2.0, and mutual authentication. Know these authentication methods for exam scenarios.

8. Response Format: The REST API Explorer allows you to specify whether responses are returned in JSON or XML format via the Accept header. JSON is the default and most commonly used format in modern ServiceNow development.

9. PUT vs. PATCH: This is a subtle but testable distinction. PUT replaces the entire record with the data provided (fields not included are set to empty/default). PATCH only updates the fields specified, leaving all other fields unchanged. In practice, ServiceNow's Table API PATCH is the safer choice for partial updates. Exam questions may test this distinction.

10. Eliminate Distractors: When you see answer choices that mention tools like SOAP Message, Web Service Import Set, or MID Server in the context of testing REST APIs, these are usually incorrect. The REST API Explorer is the primary tool for exploring and testing REST APIs within ServiceNow.

11. Role Requirements: To access the REST API Explorer, a user typically needs the admin role or the rest_api_explorer role. This may come up in scenario-based questions about permissions.

12. Practice in a PDI: If possible, access a Personal Developer Instance (PDI) and use the REST API Explorer hands-on. Navigate through each API, test different methods, and generate code snippets. This practical experience will help you answer scenario-based questions with confidence.

Summary

The REST API Explorer is a powerful, built-in ServiceNow tool that enables developers to discover, test, and generate code for REST API calls. It supports all standard ServiceNow APIs and any custom Scripted REST APIs on the instance. For the CAD exam, focus on understanding its purpose (inbound REST testing), its location in the navigator, the key query parameters, HTTP method mappings, and the distinction between inbound REST (REST API Explorer) and outbound REST (REST Messages). With a solid grasp of these concepts, you will be well-prepared to answer any exam question related to the REST API Explorer.