# Integration Basics and REST APIs

> Chapter 13 of the Courseiva SERVICENOW-CAD curriculum — https://courseiva.com/learn/servicenow-cad/integration-basics-and-rest-apis

**Official objective:** 7.1 — Integrate ServiceNow with external systems using REST APIs and web services

## Introduction

Exam objective 7.1 demands that you understand how to make ServiceNow talk to other software systems. Integration Basics and REST APIs are the tools that make this conversation possible, allowing data to flow between ServiceNow and everything from email platforms to external databases. For the SNOW-CAD exam, you must grasp not just what REST is, but how to configure it in ServiceNow to automate real business processes.

## The Restaurant Kitchen Order System Analogy

A restaurant kitchen has its own way of working. The chefs have their recipes, their stoves, and their chopping boards. But the kitchen doesn't know what customers want until someone tells them.

In this scenario, a waiter acts like an integration method. A customer at a table wants a specific meal — a cheeseburger with no onions and extra pickles. The waiter writes this request on a standard order slip. This slip is the REST API request. It has a clear structure: the customer's table number (the endpoint), the items requested (the data), and a request type like 'new order' (the HTTP method, POST). The waiter walks to the kitchen and hands the slip to the head chef. The chef reads it, cooks the burger exactly as specified, and plates it. The waiter then takes the completed order back to the customer.

The kitchen does not need to know how the customer's table looks. It only needs the order slip. Similarly, an external system does not need to know how ServiceNow structures its internal records. It just sends a properly formatted REST API request. The response — the cooked meal — is the data or confirmation that ServiceNow sends back. This whole system replaces the old way where a manager would shout orders across the room, causing confusion and errors. REST APIs bring the same standardisation and clarity that a written order slip brings to a busy kitchen.

## Core explanation

Integration is simply the act of making two separate systems work together. Think of it as teaching two people who speak different languages to communicate clearly. In IT, systems often need to share information. For example, when a customer submits a support ticket on a website, that ticket information might need to land directly in ServiceNow as an incident record. Without integration, someone would have to copy the details manually from the website and type them into ServiceNow. That is slow and error-prone. Integration automates this transfer.

REST is an acronym that stands for Representational State Transfer. That sounds complicated, but it is just a set of rules for how systems ask for and send data over the internet. A REST API (Application Programming Interface) is the specific doorway that a system like ServiceNow opens so that other systems can interact with it. When you use a REST API, you are making an HTTP request. HTTP (Hypertext Transfer Protocol) is the same protocol your web browser uses to load websites. Every request has a method, which is the action you want to perform. The most common methods are GET (to retrieve data), POST (to create new data), PUT (to update existing data), and DELETE (to remove data). These are sometimes called CRUD operations: Create, Read, Update, Delete.

So, how does this work in practice? An external system — say, a cloud-based HR tool — wants to create a user record in ServiceNow. It constructs an HTTP POST request. This request has several parts:

- A URL called the endpoint. This is the specific address on ServiceNow where the user records live. It looks something like https://yourinstance.service-now.com/api/now/table/sys_user.
- Headers that provide metadata, like the type of data being sent (usually JSON) and authentication credentials.
- A body that contains the actual data, formatted as JSON (JavaScript Object Notation). JSON is a lightweight way to write data as key-value pairs, like {"name": "Jane Doe", "email": "jane@example.com"}.
- An authentication method. ServiceNow does not let just anyone send requests. The external system must prove it has permission. Common methods include Basic Authentication (using a username and password) or OAuth (a token-based system that is more secure).
- ServiceNow receives the request, checks the authentication, parses the JSON data, and creates a new record in the sys_user table. It then sends back a response. This response includes a status code. A 200 or 201 status code means success. A 400 code means bad request (you sent something wrong). A 401 means unauthorised (your credentials are invalid). A 404 means the endpoint was not found. A 500 means the server had an internal error.

Why does this matter for the SNOW-CAD exam? ServiceNow provides several tools to work with REST APIs. One is the REST API Explorer, a built-in tool where you can test API calls interactively without writing code. Another is creating custom REST API endpoints using Scripted REST APIs, where you can write server-side JavaScript to define exactly what happens when a request arrives. On the other side, you can configure ServiceNow to make outbound REST calls to external systems using the RESTMessageV2 class in business rules or scripts. This allows ServiceNow to send alerts to Slack, update a CRM system, or fetch weather data.

Integration replaces manual data entry, reduces human error, and enables real-time synchronisation between systems. Before REST APIs became the standard, systems often used SOAP (Simple Object Access Protocol), which was heavier and more rigid. REST is lighter, faster, and more flexible because it uses standard HTTP methods and formats like JSON. Almost every modern web service, from Twitter to Google Maps, uses REST APIs. By learning this chapter, you are learning how to connect ServiceNow into this wider ecosystem of software.

## Real-world context

Consider an IT helpdesk at a mid-sized company. Employees submit IT support requests through a web portal that is not ServiceNow. The portal uses a simple database to store tickets. However, the helpdesk team uses ServiceNow to manage and track all incidents. Every time an employee submits a ticket on the portal, someone must manually copy the details and create a new incident in ServiceNow. This takes about three minutes per ticket. With two hundred tickets a day, that is ten hours of wasted labour per week.

An IT professional would solve this by building an integration using REST APIs. Here is the step-by-step process they would follow:

- First, they would identify the endpoint on ServiceNow where new incidents are created. That endpoint is typically /api/now/table/incident.
- Next, they would generate API credentials, either a username and password pair with the correct roles, or an OAuth token. They would ensure the account used has the 'rest_service' role and write access to the incident table.
- Then, they would work with the portal developer to configure the external portal to send an HTTP POST request to that endpoint every time a ticket is submitted. The request body would contain the JSON-formatted data, mapping the portal's fields to ServiceNow fields: the short description, the caller's email, the category, and the priority.
- They would also handle the response. If ServiceNow returns a 201 Created status along with the new incident sys_id (the unique identifier), the portal can display that ID to the user as a reference number. If it returns a 400 or 500 error, the portal should show an error message and possibly retry.
- Finally, they would test the integration thoroughly. They would create a test ticket on the portal, check that an incident appears in ServiceNow with the correct fields, and confirm that the response is handled correctly. They would also set up logging to capture any failed requests for debugging.

After this integration runs, the manual copy-paste work disappears. Incidents appear in ServiceNow within seconds of the employee hitting submit. The helpdesk team can start working on tickets immediately. The IT professional also gains a reputation for solving a tedious problem elegantly. They have used a REST API to connect two separate software worlds, eliminating a bottleneck and improving the company's efficiency.

## Exam focus

The SNOW-CAD exam objective 7.1 focuses specifically on your ability to design and implement integrations using REST APIs and web services from within the ServiceNow platform. The exam does not test general networking knowledge but expects you to know ServiceNow's specific tools and syntax.

The exam loves to test the following concepts:

- The difference between inbound and outbound REST calls. An inbound call is when an external system sends a request to ServiceNow. An outbound call is when ServiceNow sends a request to an external system. You must know which tool to use for each. For inbound, you use Scripted REST APIs or the built-in Table API. For outbound, you use the RESTMessageV2 class in a script.
- Authentication methods. The exam frequently asks about Basic Authentication versus OAuth. OAuth is the more secure and modern approach. You should memorise that OAuth involves obtaining an access token from an OAuth provider, which then expires and can be refreshed. ServiceNow can act as both an OAuth provider and an OAuth client.
- HTTP methods and status codes. The exam will expect you to know that GET retrieves data, POST creates, PUT updates, and DELETE removes. For status codes, know the most common ones: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorised, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, and 500 Internal Server Error.
- JSON format. You will see JSON examples in questions. You need to recognise the structure: objects are inside curly braces, arrays are inside square brackets, and data is stored as key-value pairs separated by colons. A common trap is the order of keys in JSON — it does not matter.
- The role of the 'rest_service' role. Users who make REST API calls to ServiceNow must have this role, or the system will return a 403 Forbidden. The exam may present a scenario where a REST call fails and you must identify the missing role as the root cause.

Common exam traps include:

- Confusing GET and POST. A GET request should never create data, but some beginners think you can put data in the URL to create a record. That is incorrect. GET is for reading only. POST is the correct method for creating.
- Forgetting to include authentication in the header. A question might describe a well-formed REST request that still fails. The correct answer is often that the request is missing an Authorization header or the credentials are incorrect.
- Mixing up the endpoint for Table API versus Scripted REST API. The Table API uses a standard endpoint like /api/now/table/incident and provides basic CRUD operations. Scripted REST APIs allow custom endpoints and logic, defined by the developer.
- Thinking that REST APIs are stateless only in name. The exam might ask about state management. REST APIs are stateless, meaning each request contains all the information needed. ServiceNow does not remember previous requests. If you need to maintain state, you must handle it in your application logic, not rely on the API.

To pass this section, you should practise using ServiceNow's REST API Explorer. Understand how to construct a request, set headers, and read the response. Memorise the key HTTP status codes and their meanings. Finally, understand the difference between the Table API and Scripted REST APIs, because the exam will test your ability to choose the right tool for a given requirement.

## Step by step

1. **Identify the Endpoint** — Find the exact URL on the target system (either ServiceNow or an external system) where you will send the REST request. For ServiceNow's Table API, the endpoint follows the pattern /api/now/table/{table_name}. For example, to work with incidents, the endpoint is /api/now/table/incident. Getting this wrong causes a 404 error.
2. **Choose the HTTP Method** — Decide what action you want to perform. Use GET to retrieve data, POST to create a new record, PUT to replace an entire record, PATCH to partially update a record, and DELETE to remove a record. Using the wrong method will either fail or produce unexpected results. For instance, sending a GET request with a body to create a record will be rejected.
3. **Set Up Authentication** — Configure how the calling system proves its identity. For ServiceNow inbound calls, you typically use Basic Authentication with a username and password, or OAuth with an access token. Without proper authentication, the system returns a 401 or 403 status code. The user must have the 'rest_service' role for the request to succeed.
4. **Construct the Headers and Body** — Headers include metadata like the Content-Type (usually application/json for JSON data) and the Authorization header with your credentials. If using a method like POST or PUT, you also need a body containing the data to send. Format the body as a JSON object with the relevant field names and values. Any mismatch in field names will cause the data to be ignored or cause an error.
5. **Send the Request and Handle the Response** — Make the HTTP request to the endpoint. The system processes it and sends back a response containing a status code and often a body with the resulting data or an error message. You must check the status code to determine success or failure. A 201 Created means the record was created successfully. A 400 Bad Request means your data was invalid. Practise reading the response body to debug issues.

## Comparisons

### Table API vs Scripted REST API

**Table API:**
- Provides automatic REST access to any table without writing code.
- Endpoints follow a fixed pattern: /api/now/table/{table_name}.
- Supports only standard CRUD operations on table records.

**Scripted REST API:**
- Requires writing custom server-side JavaScript to define behaviour.
- Endpoints are custom and defined by the developer, e.g., /api/x_example_custom/createTicket.
- Allows complex logic, validation, and aggregations beyond simple CRUD.

### Basic Authentication vs OAuth Authentication

**Basic Authentication:**
- Uses a static username and password sent in the request header.
- Less secure because credentials are sent with every request and can be intercepted.
- Does not support token expiry; requires a password change to revoke access.

**OAuth Authentication:**
- Uses a temporary access token obtained from an OAuth provider.
- More secure because tokens expire and can be refreshed without exposing passwords.
- Supports scopes and granular permission controls.

### GET Method vs POST Method

**GET Method:**
- Used to retrieve data from the server.
- Has no body; parameters are passed in the URL query string.
- Should never create or modify data on the server.

**POST Method:**
- Used to create new data on the server.
- Includes a body with the data to be created, formatted as JSON or XML.
- Should always result in a side effect on the server (new record created).

## Diagram

_This diagram shows the flow of a typical REST API call from an external system into ServiceNow, including the authentication check and response handling._

```mermaid
flowchart TD
    A[External System] -->|Sends HTTP POST Request| B[ServiceNow REST Endpoint]
    B --> C{Authentication Check}
    C -->|Success| D[Parse JSON Body]
    C -->|Failure| E[Return 401 or 403]
    D --> F[Create/Update/Delete Record]
    F --> G[Return 201/200 with sys_id]
    D --> H[Error in Data]
    H --> I[Return 400 Bad Request]
```

## Common misconceptions

- **Misconception:** REST APIs only work with JSON and nothing else. **Reality:** REST APIs can work with multiple data formats, including XML, plain text, and even binary data. JSON is the most common and recommended format, but it is not the only one. (Many beginners encounter only JSON in examples and tutorials, so they assume it is the only option. The exam may present a scenario where XML is used, and candidates need to know that it is still valid.)
- **Misconception:** You need to install a plugin or additional software to use REST APIs in ServiceNow. **Reality:** REST APIs are built into every ServiceNow instance. You do not need to install anything. The REST API functionality is available out of the box, including the REST API Explorer and the Table API. (New users often assume that such a powerful feature requires extra licensing or setup. They look for plugins in the wrong place and waste time. The exam expects you to know it is native.)
- **Misconception:** A REST API call will fail if the JSON data is sent with the keys in a different order than expected. **Reality:** JSON objects are unordered collections of key-value pairs. The order of keys does not matter. ServiceNow parses the keys regardless of the order in which they appear. (People often bring expectations from programming languages where array order matters. JSON objects are different. This misconception leads to wasted debugging time.)
- **Misconception:** REST APIs are only for creating new data, not for reading or updating existing records. **Reality:** REST APIs support all CRUD operations: Create (POST), Read (GET), Update (PUT or PATCH), and Delete (DELETE). Using them only for creation is a severe underutilisation of the standard. (Beginners often associate APIs with form submissions that create new records. They forget that querying existing data is also a core use case. The exam tests this understanding directly.)
- **Misconception:** You must write a Scripted REST API to expose any data from a table. **Reality:** ServiceNow's Table API automatically exposes all tables through a standard REST endpoint. You do not need to write any code to allow external systems to read or write to a table. Scripted REST APIs are only needed for custom logic or complex validation. (This misconception comes from developers who assume you always need custom code. The Table API is one of the most powerful out-of-the-box features, and the exam expects you to know when to use it versus when to write a custom API.)

## Key takeaways

- REST is a standard set of rules for making HTTP requests to retrieve or manipulate data, and it is the most common way to integrate ServiceNow with other systems.
- Every REST API call requires an endpoint URL, an HTTP method, headers for authentication and content type, and optionally a body format like JSON.
- ServiceNow's Table API provides automatic REST access to any table without custom coding, using endpoints like /api/now/table/incident.
- HTTP status codes tell you whether your API call succeeded: 200-299 means success, 400-499 means a client error, and 500-599 means a server error.
- OAuth authentication is more secure than Basic Authentication because it uses temporary tokens that can expire and be refreshed.
- The RESTMessageV2 class is the primary way to make outbound REST calls from ServiceNow scripts to external systems.
- JSON data is unordered, so the sequence of keys in your request body does not affect how ServiceNow processes it.

## FAQ

**What is the difference between a REST API and a web service?**

A REST API is a specific type of web service that follows the REST architectural style. All REST APIs are web services, but not all web services are REST. The other common type is SOAP, which uses XML and is more rigid. For the SNOW-CAD exam, focus on REST.

**How do I find the REST API endpoint for a specific table in ServiceNow?**

The endpoint for any table in ServiceNow is /api/now/table/{table_name}, where {table_name} is the actual table name from the database, like 'incident', 'sys_user', or 'task'. You can find the table name by looking at the sys_db_object table in ServiceNow.

**What does the status code 401 mean when I call a REST API?**

A 401 status code means Unauthorised. This indicates that the request lacks valid authentication credentials. You likely forgot to include the Authorization header, or the username/password or token is incorrect. Check your authentication setup.

**Can I use REST APIs to update multiple records at once?**

The standard Table API works with one record per request. To update multiple records, you would need to send multiple PUT or PATCH requests, or write a custom Scripted REST API that accepts a list of records in the body and processes them in a loop.

**What is the 'rest_service' role and why do I need it?**

The 'rest_service' role is a ServiceNow role that must be granted to any user who wants to make REST API calls to the instance. Without this role, the request will be denied with a 403 Forbidden status. It is a security measure to control who can use the API.

**Is JSON the only format I can use in a REST API request body?**

No. While JSON is the most common and recommended format, REST APIs can also accept XML, plain text, or form data. The Content-Type header tells the server which format you are using. ServiceNow's Table API accepts both JSON and XML.

## Check your understanding

1. **What HTTP method should you use to create a new incident record using a REST API?**

   Answer: You should use the POST method, as it is designed to create new resources on the server.

2. **What status code indicates that a REST API request was successful and a new record was created?**

   Answer: A 201 Created status code indicates that the request was successful and a new record was created.

3. **Which ServiceNow role must a user have to make REST API calls to the instance?**

   Answer: The user must have the 'rest_service' role assigned to their account.

4. **What class do you use in a ServiceNow script to make an outbound REST call to an external system?**

   Answer: You use the RESTMessageV2 class to construct and send outbound REST calls from ServiceNow.

5. **What does a 404 status code mean when you receive a response from a REST API?**

   Answer: A 404 status code means Not Found, indicating that the endpoint URL you requested does not exist on the server.

---

Interactive version with quiz and diagrams: https://courseiva.com/learn/servicenow-cad/integration-basics-and-rest-apis