While many people working in the technology field may have heard of REST APIs they may not know what a REST API actually is – and why they exist at all. In this article we explore what an API is, what makes an API a REST API, and why REST APIs are important for creating interoperability and integrations between software systems.
Before we begin...what's an API?
Good question. An API is an Application Programming Interface – and it does exactly what is sounds like it does. It provides an Interface that developers can use to write a Program to control an Application. Or for the official definition: An API is a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.
Your favorite websites or web-based services – including Facebook, Twitter, Youtube, travel sites, and nearly every major newspaper in the world – have published APIs which expose their information (posts, likes, videos, tweets, or even the latest news) so that developers can create new ways to visualize or interact with the information / services contained within each site.
Still don’t understand? Think of Trivago. Trivago is a hotel booking site that uses the APIs of hotel booking sites (hotel websites, Expedia, Booking.com) to aggregate data for users so that they can find the cheapest possible rate for a hotel. Without APIs a web based service like Trivago could not exist.
Cool. So what, exactly, is a REST API?
REST is an architectural style for distributed hypermedia systems.
REST stands for REpresentational State Transfer Application Programming Interface. Of course, that might not mean much to you right now, so let us delve deeper into what they are, what they are used for and when you can do with them.
REST APIs are almost always accessed over HTTP or HTTPS – an application protocol that forms the foundation of data communication on the World Wide Web (or, as we like to say, the Internets). This gives REST one of its greatest strengths – it is ubiquitous. It is one of the standards that drives the Internet. As a result, it is a technology that is understood and utilized by most developers.
REST Clients “request” information from REST Servers (e.g. Facebook’s back-end servers) with requests, and the Servers “serve” data back to the Clients which then decode and display the requested information (e.g. a web page) to a user.
That being said, many programs act as REST Clients. A few examples include cURL, Postman, and Insomnia. Custom developed middle ware created specifically to link two systems together can also act as a REST Client and there are many web automation platforms out there right now like Zapier that act as both REST Clients and Servers to enable integration of web based services.
Another one of REST API’s greatest strengths is simplicity. Existing integration tools like SOAP, XML-RPC and others were very flexible and powerful, but harder to work with because they weren’t supported in browsers.
Learning from the shortcomings of older technologies REST APIs adopted three general rules:
- Use standard protocols and methods (HTTP/S, along with its different methods, GET, PUT, DELETE, etc. each giving context and meaning).
- Requests should not interfere with each other, should not require serial requests to achieve a result, and previous requests should not interfere with each other. This is also known as statelessness.
- Requests should be uniform.
These basic rules were extended to form the six guiding architectural constraints which separate a REST API from other types of programming interfaces, seen below.
These constraints limit the methods that can be used by a server to process and respond to client requests and were designed to ensure that any interface built with a REST API will have good performance, be scalable, be simple, be malleable, be portable, and be reliable.
So...how did REST become a thing?
REST APIs quickly rose to be a dominant tool in the field of software engineering, for many good reasons. But every success story starts somewhere. In our case, even though the exact place varies, REST’s story essentially began in the early 2000s.
REST Beginnings
The first mentions of REST come from the works of Dr. Roy Fielding, a researcher in computer science, in his dissertation entitled “Architectural Styles and the Design of Network Based Software Architectures”. Dr. Fielding introduced the basic concepts of REST and additional complimentary details. Spanning 180 pages, the paper went over how software developers could use existing technology to make robust and powerful tools while keeping things simple. This paper laid the foundation that led to the formation and evolution of simpler APIs – including REST.
REST On the Rise
The earliest adopters of simplified APIs were ecommerce platforms. The first major and publicly available REST API was put out by eBay on November 20, 2000. Limited to a few partners originally it set the benchmark for any future APIs to come out. Amazon.com published their own API in 2002. Then came social networks, with first Flickr (2004), then Facebook (2006), and Twitter (2006).
These APIs served multiple purposes. First – they allowed the creation of complimentary platforms. Suddenly eBay was no longer just the website eBay. It became a data repository for anyone with the ability utilize the API, spreading eBay’s reach far around the Internets, giving birth to more online shops, all depending on eBay. This, in turn, increased the value of eBay, generating more sales for eBay, more advertising spend, and a continual stream of people joining to build their own tools and shops on top of their API. Although eBay’s popularity has declined in the past years, their API was a revolution and changed the way e-commerce worked forever.
Second – they allowed more control over a company’s data and with lower costs. Scraping (using a robot to go collect information on a web page) was a costly thing for eBay – and for most companies. By introducing an API, they could greatly reduce the amount of robots (software programs that searched, indexed, and stored metadata about their site) they needed to use, lower costs, and programmatically control access to their data. Through the use of API keys or tokens bad actors (people abusing the API) could quickly be evicted, while people with good business cases saw a standardization in how a company’s data could be accessed dependably.
While more companies were building their own APIs to give access to their own services – e.g. Cloud Computing – one saw more potential in that – Amazon. Amazon originally built Amazon Web Services (AWS) to guarantee access to their online shops. Over time Amazon began reorganizing itself in smaller entities, all connected together by APIs. At first, this gave them greater flexibility, allowing teams to perform changes rapidly, as long as they didn’t change the outside-facing API.
Then, in March 2006, Amazon changed everything. They launched AWS with a new purpose: providing a cloud-based computing platform that could be used to rapidly build and grow web-based services (like Dropbox). AWS services were no longer restricted to Amazon’s internal use The first service launched, Amazon S3, is a mass storage service. By making it accessible through a REST API and selling access to computing resources, people could now start building not just tools around platforms, but platforms themselves. Amazon EC2 would provide computing resources in the cloud, allowing people to run servers, move to more powerful machines when needed. Gone were the days of needing to rent space in a server room and buying your own hardware. You could now launch new servers in the span of seconds, get reliable backups and content delivery, all accessible through simple APIs. Today, Amazon is the biggest cloud provider in the world, showing that their strategy worked. While not responsible for the rise of cloud computing, REST APIs, through their ease of use, certainly contributed to a faster growth of it.
No rest for REST APIs
Platforms would once again take the spotlight a few years later, with the rise of smartphones. Applications were no longer only available via a web browser on a computer – they exploded across Google’s Android and Apple’s iOS as both companies introduced online marketplaces that made downloading and installing smart phone apps simple and straightforward. These apps would need back-end dependable, scalable computing resources as they experienced rapid growth – and AWS was there to answer the call. Many apps today are not only built using REST APIs, but have their own REST APIs as well.
Today, REST APIs are everywhere. To say they have won the API war in not an understatement. And while they may one day be dethroned themselves by newcomers (gRPC, GraphQL, etc.), they currently stand at the top of the API game and – because of their ubiquity – will likely stay there for a long time.
Today having a strong understanding of REST APIs is expected of any software developer as most SaaS (Software as a Service) tools are built with with their own REST APIs. And REST APIs are everywhere. As of 2018, an estimated 85% of APIs online were REST APIs (or a close variant). Billions of requests are made to these APIs every day – and they drive interoperability not only on the web, but with offline products like DW Spectrum.
REST API in DW Spectrum VMS
DW Spectrum Server API – a RESTful API
The DW Spectrum Server API is a RESTful API that can be used to integrate 3rd party devices and systems with DW Spectrum VMS.
The diagram at the beginning of the article and above shows a very simplified process that outlines (pun intended) the way 3rd party products can integrate with DW Spectrum VMS using the DW Spectrum Server API and the Do HTTP Request action in the DW Spectrum VMS Rules Engine. Yep – that’s right – DW Spectrum can act as both a REST Client and a REST Server, allowing developers to use DW Spectrum VMS as a situational awareness platform that integrates with all of their existing complimentary systems.
Common use cases for the API and Do HTTP Request action include:
- Sending Events from 3rd party devices / systems to DW Spectrum for use in creating system automation in the DW Spectrum Rules Engine.
- Pulling live or recorded video from an DW Spectrum system to play back in a 3rd party interface.
- Sending API calls to 3rd party devices (e.g. Access Control locks, IoT devices) and systems (e.g. Access Control, Fire, and Alarm) to extend the control capabilities of a system operator using DW Spectrum.
- And….many more use cases.
Accessing the Server API
The DW Spectrum Server API documentation is available in the Server Web page. It’s built in to DW Spectrum VMS.
- Install DW Spectrum IPVMS (follow the instructions in #2 of Check Out DW Spectrum article)
- Right click on a Server in the Resource Panel and choose Server Web Page
- Log in with your username and password
- Click on the For Developers tab and navigate til you find the API Documentation link (hint its under Server API) and click on it to view.
- Don’t forget to check out the Generic Event Generator Tool - which helps format how data can be quickly sent to DW Spectrum