Chapter 1
Conceptual Asides
For a long time, I kept myself away from the adventurous and thrilling world of Integrations. However, integration is actually a very simple concept and it is so much fun to do. And ServiceNow is a great tool when it comes to integrating with other tools.
ServiceNow community have many great people around the globe, who not only did lot of crazy stuff but also helped many many others like me to understand these concepts. Also ServiceNow itself has a great amount of resources, learning paths, courses and well-structured documentation that you can take advantage of. But sometimes it can be difficult to read and understand all this tech terms of official documentations, And it can be very easy if they are consolidated at one place with practical use cases. Which is exactly the journey I will be taking you all on. Whatever you are going to learn in this journey is not something I came up with, It is already there! But what we will be doing is connecting the dots, going step by step through each concept building on previous ones. In other words, I am going to teach you "How to read the docs", but I promise by end of all these chapters, you will be able to build almost any integration in the world; though I'm going to restrict myself to ServiceNow platform, when explaining all those stuff.
Well, That's a big committement! and in order to make it true, we need to think of some concepts that are essential to understand before we actually dig deeper. Don't worry, we'll go pretty quick through them in this chapter and touch them back once we actually do the tech part.
What is API
When you chat with a friend, you need a mobile (or in other words, a communication device) to do that. Or in order to open a door you need a handle. Application Programming Interface or API is a similar concept, and it helps two programs to communicate & enable exchange of information with each other.
Let us try to understand this another way. Think that you are hungry and want to eat a pizza. You go to the nearest restaurant, check the menu and make the order to the waiter. Waiter in turn takes the order to the kitchen, brings the pizza from the kitchen and deliver the pizza to your table. The waiter plays the similar part as of the API.
In IT world, Client application requests information from a server. A server processes the request and returns a status code and a response body. When the response body is returned, the Client extracts information from the response body and takes action on the extracted data. API is a mid layer that handles this communication. Scripted REST Services allow developers to create their own APIs on the ServiceNow Platform.
What is REST API
Representational state transfer or REST is the most popular approach of building APIs. When a request for data is sent to a REST API, it’s usually done through hypertext transfer protocol (HTTP). Once a request is received, APIs designed for REST can return messages in a variety of formats: HTML, XML, plain text, and JSON.
A request is made up of four things:
- The Endpoint
- The method
- The headers
- The body
The Endpoint
The endpoint is the url you request for. It generally consists of base path and resource path. E.g.
https://dev124645.service-now.com/api/now/table/incident
Every web service provider will have the API documentation and that needs to be referenced in order to configure the HTTP method endpoint.
The method
HTTP methods define the action to take for a resource, such as retrieving information or updating a record. The available HTTP Methods are:
POST: Create
POST method is used to submit the information to the server.
GET: Read
GET method is the most common of all the request methods. It is used to fetch the desired resource from the server.
PUT/PATCH: Update
Both PUT & PATCH are used to modify the resources on the server with a slight difference. PUT is a method of modifying resource where the client sends data that updates the entire resource. PATCH is a method of modifying resources where the client sends partial data that is to be updated without modifying the entire data.
DELETE: Delete
POST method is used to delete the resource identified by the request url.
HTTP Headers
Client and Server can pass the extra bit of information with the request and response using HTTP headers. The Server determines which headers are supported or required.
The most widely used HTTP Headers are:
- Accept
- Content-Type
- Authorization
- Access-Control-Allow-Origin
- Access-Control-Allow-Methods
Accept
Type of data client can understand.
Content-Type
Specifies the media type of the resource.
Authorization
Used to pass credentials so that server can authenticate. Different web service providers may require different types of authentication.
Access-Control-Allow-Origin
Specifies which origin is allowed to access the resources.
Access-Control-Allow-Methods
Specifies which methods are allowed to access the resources.
Accept vs. Content-Type
As we have discussed above, Accept is the type of data client can understand, whereas Content-Type specifies the media type of the resource.
What this actually means is that The Accept header is used to inform the server by the client that which content type is understandable by the client expressed as MIME-types. By using the Content-negotiation the server selects a proposal of the content type and informs the client of its choice with the Content-type response header.
I assume, almost all of you have worked in the Operations team. And you might have receieved an incident or an request from the user, who understand only french or german, while you can only speak english. Lets say, in such instances you might use some kind of translator to convert your response in user-specific language to respond to the user. Let us consider, user does the same and convert his response into english that you understand. Now if you are asking user for an input by this means, The language in which you did respond to the user (french/german) will be an Accept and the language in which you did receieve the response (i.e. english) will be a Content-Type.
Both this headers are expressed by as MIME-types. E.g.
Content-Type:application/json;
HTTP Status Codes
I'm sure you have came across the scenerio, when you tried to access a webpage and recieved an 404 (Page not found) or 403 (Access Forbidden) error? This are status codes.
Server always returns the HTTP status code with the response. The HTTP status codes refer to the interaction with the REST service provider. The status codes do not tell anything about the requested data. ServiceNow APIs return standard HTTP status codes.:
- 1xx: Informational
- 2xx: Success
- 3xx: Redirection
- 4xx: Client Error
- 5xx: Server Error
HTTP Query Parameters
HTTP Query Parameters are appended to the endpoint url after '?'. The query parameters are specific to the selected API method and control what information developers using the API can pass in the API request URL.
https://dev124645.service-now.com/api/now/table/incident?sysparm_query=active%3Dtrue&sysparm_limit=10
Path Parameters
Path parameters are enclosed in curly braces in the endpoint URL. The values set in the path parameter field are substituted into the endpoint URL when a request is sent. This makes the endpoint dynamic and more useful.
https://dev124645.service-now.com/api/now/table/{tableName}
Outbound vs. Inbound REST Integrations
When ServiceNow consumes a web services from third party providers and other ServiceNow instances, It is considered as a Outbound REST Integration. Whereas, In an inbound request, a third-party application requests an action through a ServiceNow API.
Outbound REST Integration
Inbound REST Integration
What's next?
In next chapter, we will see some of the concepts & methods related to javascript JSON and Objects, before diving into actual ServiceNow integration jungle. Knowing this simple concepts will be extermely helpful and will make us confident about the code that we are going to write. Believe me, you are going to use hell lot of JSON.