Amplience provides many APIs to manage and deliver content. What exactly is an API, what does it stand for, and why are there so many different flavors? In this article, we’ll take a look at how API technologies have evolved and why. We will highlight how you can leverage the capabilities of Amplience APIs in your own applications.
What is an API?
API stands for Application Programming Interface. This acronym has been in use by software developers since the dawn of computing. It generally refers to how two software systems can interact. These days, systems are often separated by a network. So, when we talk about APIs in this context, we are usually talking about web APIs.
There are many web-based API technologies. In this article, we will explore a little history before focusing on the popular ones. They are: HTTP, REST, and GraphQL. We’ll also discuss why a service might choose to offer its API in a given type.
Rise of HTTP
The internet started as an ecosystem of government, academic and research institutions. As this ecosystem had a limited set of devices operating systems and protocols, it was homogenous. In the 1990s, the ecosystem expanded to include commercial and consumer systems. This diversification of operating systems and languages led to the heterogenous environment of today.
In the early 90s, the web emerged, allowing users to access online services through a web browser. Users could access these services regardless of their underlying operating system or device. It is the HyperText Transport Protocol (HTTP) that powered this capability. While HTTP let browsers retrieve pages, developers made use of its ubiquity for machine-to-machine communication. This allowed systems to talk to each other just as easily as browsers could talk to web servers.
Protocols such as XML-RPC and SOAP were built on top of HTTP. By using HTTP, these protocols could navigate their way through firewalls much more easily than others. Both protocols made use of XML. A clear advantage for its use over binary protocols is that XML is human-readable. It is well formatted text. This, along with standardization over how the XML was structured, led to their widespread adoption.
HTTP APIs
By the early 2000s, JavaScript was being used as a browser scripting language. It gave developers a tool to build interactivity in web pages. At this time, JavaScript Object Notation (JSON) was invented as a convenient way to exchange data, instead of XML. Its origins in-browser and its easy-to-use credentials have contributed to JSON’s popularity, and many HTTP APIs adopt JSON in preference to XML.
Amplience provides HTTP APIs for content delivery. The lightweight nature of JSON over HTTP gives great performance characteristics and is easy to use both in-browser and server-side.
REST APIs
Not all HTTP APIs are REST APIs. This is an important distinction, as there are a number of constraints that an API must satisfy to be considered RESTful.
So, what is a REST API? Representational State Transfer (REST) is an architectural style for APIs described by Roy Fielding. Some of the constraints that qualify an API as REST are widely present in HTTP APIs that aren’t RESTful. A good example is *stateless communication*. Many HTTP APIs adhere to this constraint as it has a number of benefits, particularly around visibility and scalability. However, that’s not enough to be RESTful.
For a HTTP API to be described as RESTful, it must, among other qualities, also have a *Uniform Interface*. In Fielding’s thesis, this means it should adopt hypermedia as the engine of application state (HATEOAS). The idea behind this principle is that a client should be able to navigate and interact with a REST API entirely through links that are given in API responses. This way, the client can discover available resources and actions based on the state of the system.
Our Content Management API is a RESTful API that provides HAL links that allow clients to discover our API and understand what actions are available.
GraphQL
GraphQL is an API style developed by Facebook and open-sourced in 2015. Unlike REST APIs, which require clients to use predefined endpoints and resources, GraphQL’s dynamic and flexible nature allows clients to specify exactly what data they need, giving them more control over the API. Rather than relying on specific pre-defined resources, the client can decide what data it needs and request only that data. Traditional REST APIs often require clients to make multiple requests to retrieve all the data they need. In these APIs, the resources are fixed, and so these requests might result in either over-fetching or under-fetching of data.
HTTP and REST APIs are often accompanied by some description of the structure of the API. This can be as informal as a set of documentation, or they can be formal descriptions such as WSDL or OpenAPI specifications. In GraphQL, the specification of the API is built-in. It uses types and schemas to describe the API and all possible interactions with it.
We recently introduced GraphQL endpoints for our Asset Management and delivery systems. There’s an exciting difference between these two. In our Asset Management GraphQL API, the resources that are available are fixed and defined by us: the types described in the schema are all Amplience concepts.
However, in our Content Delivery API, the resources are defined by our customers through content types. When content types are made ready, we automatically build out an updated GraphQL schema that incorporates query capabilities for content of that type. This gives our customers a rich, flexible API driven by their own content and fully uses our high-performance delivery network.
Amplience APIs
At Amplience, we strongly believe in choosing the right tool for the job. Our choice of API style follows this principle. When we need client-side discoverability, we choose REST. When we need high performance, lightweight content delivery, we choose HTTP. When we need flexible client-driven queries that avoid over-fetching and under-fetching, we use GraphQL. Take a look at our API documentation to find out more.