REST APIs - A Brief Overview
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 past challenges, HTTP-based RESTful APIs are defined with the following aspects:
- A base URI, such as http://api.example.com/collection/
- Standard HTTP methods (e.g., GET, POST, PUT, PATCH and DELETE);
- A media type that defines state transition data elements. The current representation tells the client how to compose requests for transitions to all the next available application states. This could be as simple as a URI or as complex as a Java applet.
Web service APIs that adhere to the REST architectural constraints are called RESTful APIs. There are six guiding architectural constraints which separate the REST software architecture from other types.
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 software built with a REST architecture will have good performance, be scalable, be simple, be malleable, be portable, and be reliable.
- Client-Server Architecture
A Client-Server Architecture separates the user interface (the Client) from data processing and storage (the Server) so that a system has improved portability, scalability, and malleability (ability to modify on the fly).
- Statelessness
Statelessness calls for no required continuous connection between the Client and the Server between requests – and that all requests from a Client contain all the information needed in order to execute the request. This makes the interface between Clients and Servers reliable
- Cacheability
Caching is all about making information available at the right place at the right time. Your web browser caches data from websites ( assets like images, colors, types, fonts, etc) so that it can reload them faster the next time you view them. Caching, if implemented properly, can improve the scalability and performance of an application significantly.
- Layered System
With a Layered System the Clients do not know what Server they are connected to. Layered Systems also mean that a Server can call other Servers in a System to generate a response to a request from any connected Client. This approach can improve system scalability by enabling load balancing and shared caches.
- Code On-Demand
Code on Demand means that Servers can temporarily extend of customize the functionality of a Client by transferring executional code like Java applets or client-side JavaScript. This increases the malleability of an application built on a REST API.
- Uniform Interface
The uniform interface constraint is fundamental to the design of any RESTful system. It simplifies and decouples the architecture, which enables each part of a system (e.g. the Client or the Server) to evolve independently – which makes a system more flexible and easier to maintain.
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 programatically 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 Nx Witness VMS and Nx Meta VMP.
REST API in Nx Witness VMS (and other Powered-by-Nx Products)
Nx Server API – a RESTful API
The Nx Server API is a RESTful API that can be used to integrate 3rd party devices and systems with Nx Witness 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 Nx Witness VMS using the Nx Server API and the Do HTTP Request action in the Nx Witness VMS Rules Engine. Yep – that’s right – Nx Witness can act as both a REST Client and a REST Server, allowing developers to use Nx Witness 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 Nx Witness for use in creating system automation in the Nx Witness Rules Engine.
- Pulling live or recorded video from an Nx Witness 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 Nx Witness.
- And….many more use cases.
Accessing the Server API
The Nx Server API documentation is available in the Server Web page. It’s built in to Nx Witness VMS.
- Install Nx Witness VMS (available at http://my.networkoptix.com)
- 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 and click on it to view
