Companies like Uber, Grubhub, Airbnb, and others have disrupted their industries, transformed customer experiences, and achieved massive valuations over a very short time—using teams that are a fraction of the size of their well-established competitors. You might be wondering, “Good for them, but how did they do it with limited resources? How can I apply their strategy to my own company?”
The answer is simple. They did not code their entire applications from scratch; they tapped into existing data resources to create new and innovative solutions using an Application Program Interface (API). But before you jump right into development mode, you need to understand that API integrations often become a tug of war between technical limitations and “pie-in-the-sky” functionality that non-technical stakeholders would like to see in their business toolkits.
The rapid fragmentation of the software market is accelerating the demand for seamless connectivity between web-based applications. With improved end-user experiences (UX) in mobile banking, efficiencies gained through Amazon’s 1-click purchasing, and other advances on the consumer side, business clients are raising their expectations as well. They want the ability to move data bi-directionally from one platform to another in real-time, through an engaging user experience.
However, implementing API integrations into your company’s business-critical applications on an ad-hoc basis can end up wasting your organization’s valuable resources. Without a well-thought-out plan, your developers may decide (on their own) to pursue functionality that is not feasible or may not be relevant to your business model at any given time. Consequently, it is extremely important to have an API integration strategy that is proactive, as well as reactive. Knowing what needs to be done before, during, and after you integrate third-party applications with ChangeGear is essential to the success of your integration project.
NOTE: From this point forward, we are assuming you (the reader) have a basic understanding of software development, Web services, and the ChangeGear user interface. The next few sections provide an introduction to the RESTful API, which facilitates a connection between two web-based applications. After that, things get a bit more technical as we dive into endpoints, authentication, URL syntax, parameters, and methods. If you are not comfortable (or not interested) in learning about these technical details, we recommend you skip Steps 1 and 2 and continue reading at Step 3—Perform System Integration Testing.
An Application Program Interface (API) integration is a connection between two disparate applications that allows data to flow back and forth seamlessly and without manual intervention. An API defines the types of calls (i.e., interactions) that a program can make, how it can make them, the data formats it can use, the conventions it must follow, and much more. API integrations allow businesses to run processes that keep data in sync, enhance productivity, drive revenue, and execute many other tasks ranging from general to specialized.
The REST API provides access to ChangeGear services, which allows you (via your own program) to interact with entities using simple Hypertext Transfer Protocol (HTTP) requests. The REST API opens the possibility to programmatically access and modify functionality using scripts, custom commands, and third-party services. “REST,” also known as “RESTful,” is one of the most popular types of API. While Representational State Transfer (REST) APIs were designed to be used over almost any protocol, they utilize HTTP or HTTPS to communicate between web-based applications. For optimal performance, we strongly recommend using SSL to secure the communications to and from your ChangeGear server.
The CGWebAPI service is used to create and update certain entities (e.g., Incident, Problem, and Change) and trigger workflow actions in ChangeGear. The CGWebAPI Web service also allows you to create new attachments as part of the Create and Update operations. This simplified API was created to ease the most common integration scenarios, such as create, update, and trigger a workflow action from a third-party system. To ensure a successful integration, you should complete the following pre-integration work:
Once you have completed the pre-integration research described above, it is time to start building your application integration. Using the ChangeGear REST API requires basic familiarity with software development, web services, and the ChangeGear user interface.
Resources are the fundamental building blocks of web-based applications. A resource is anything that is available via the Internet, ranging from a document or video clip to a business process or device. From an end-user’s point of view, a resource is anything that the user can interact with while moving toward some final goal. For example, a company’s Service Desk becomes a web resource simply by making the information associated with it (i.e., knowledge base articles) available and accessible on the Web. In this example, an end-user’s goal might be to find a quick and easy solution to a technical problem they are experiencing.
In order to use a web resource, you need to be able to identify it on the network (Internet) and have some way to manipulate it. The Web provides something called a Uniform Resource Identifier (URI), which is used to uniquely identify a web resource and make it addressable. Together, these two characteristics make a URI capable of being manipulated using application conventions such as HTTP and HTTPS—the data transfer protocols used on the World Wide Web (www).
Resources define the items or entities in ChangeGear that are affected by an HTTP or HTTPS (secure) request. ChangeGear resources are exposed through the REST API using Uniform Resource Identifiers (URI), which specify the logical locations of resources on the server. The client needs to know the URI in order to access the correct resource. There is often confusion between a Uniform Resource Identifier (URI) and a Uniform Resource Locator (URL). A URI defines the location of a resource, but it does not necessarily need to specify the protocol used to access that resource. A URL is a type of URI that specifies where a resource exists (i.e., location) and the mechanism for retrieving it (i.e., protocol). Technically, the REST API uses URLs, since you need to specify either the HTTP or HTTPS protocol when accessing a resource.
Here are just a few key points that you should consider before building your application integration:
The base URL (e.g., https://changegear-server/CGRestAPI/api) defines where the REST API is located. An entity specifier (e.g., Entity) is required when using the GET or DELETE methods. The type (e.g., IncidentRequest) of entity or resource that is being accessed needs to be designated next. Finally, the unique identifier (e.g., 4) of the entity or resource being accessed is designated at the end of the URL.
Remember that the “key points” listed above represent just a few of the steps needed to successfully complete your REST API integration project. More detailed information regarding REST API Integrations is available in the ChangeGear Desktop Client Guide.
Once you have completed building your application integration, you are halfway to the finish line. We say only “halfway” because there are still so many unanswered questions. In any software development project, things get very interesting when we connect all the moving parts together and watch what happens.
A software deployment is like turning the key (or pressing the button) to start your car. Just because the engine runs, it does not guarantee that your car will drive properly. You might be sitting on a flat tire, the timing belt might be ready to snap, the transmission might be leaking fluid, or a myriad of other potential issues may be lurking under the hood. You may be sitting in the driver seat wondering, “Are the gears properly meshing (functionality)? Can the parts survive normal torque (reliability)? How fast does the transmission shift in response to the engine’s revolutions per minute (performance)? Are there any loose parts that may cause the entire system to overheat (security)? These are some very important questions that need to be answered before deploying your integration project to a live/production environment.
Application Programming Interface (API) testing is a type of software testing that performs verification directly at the API level. It is part of System Integration Testing (SIT), which determines whether the API meets your expectations for functionality, reliability, performance, and security. Effective testing requires you to:
At one time or another, we have all been frustrated when a web-based application crashed and the only clue you received was a very general “500 Internal Server Error.” This error means something went wrong, but the server could not provide you with any specific details. The key to the long-term scalability of your application integration is to make testing part of a continuous feedback cycle. If an API component fails to function properly within its larger system, you should have a monitoring tool in place to notify you of the problem as soon as it happens. That way, when an unannounced update to a third-party application’s endpoint “breaks” your system, you should have enough information to address the problem.