API Technologies
API Technology Topics
In a technology-leaning conversation about APIs you can quickly end up in a place where unknown API terms and API technologies are being thrown around. Understanding the basic terminology with regard to different types of APIs, different schema, and different API specifications will allow you to better navigate the world of APIs. Below is a summary of some of the most common definitions associated with API technologies.
We start by defining each of the three API technology topics that will be covered in this section.
Types of APIs: There are various ways to create interfaces for your applications to share data with one another. Think of these types of APIs as the mode of interaction. For example, if you need to deposit a check in your banking institution, you likely have three options: eDeposit through online banking, ATM, or bank branch teller.
While requests and responses are fundamentally transmitting the same data, the form of the data and the way it’s being transmitted differs greatly. Types of APIs are similar in this regard; they each provide a different interface for exchanging data.
Schemas: The term schema refers to the organization of data as a blueprint of how the API data is structured. The schema defines common data structures used in your API. For example, an API might return the following data:
The API schema for this data might look something like this:
An API specification expresses the overall behavior of the API, how it links to other APIs, and what the user should expect while interacting with the API. At the highest level, an API spec is a holistic explanation of the API.
The API schema for an API is typically provided within the API specification. Think of a spec as the overall “dissertation” of an API. By reviewing the API specification, you will be able to discern the general design philosophy of the API and how to interact with it.
Types of APIs
REST (Representational State Transfer)
REST has become the most widely adopted framework for APIs in the last decade. The framework for API calls is broken into four key functions described as “CRUD” (Create Read Update Delete).
The action-oriented framework has provided structure and convention to the types of actions that are performed using an API. With the proliferation of automated programming interfaces, REST has struck a balance between structure and ambiguity that has worked for the widely adopted use cases it serves.
GraphQL (Graph Query Language)
GraphQL is relatively new to the API party and serves as both an API type and schema. It is an open source technology originally created by Facebook. The philosophy behind GraphQL is a sound one: APIs should be viewed as data sources the same way data tables exist in a database (in a single graph of data).
We love GraphQL at Aloi. We believe that its adoption is extremely helpful when exposing an application to the external world. It allows users to interact with the API and retrieve data in the ways they choose.
Learn more about GraphQL here.
SOAP (Simple Object Access Protocol)
SOAP was created at a time when the need for software applications to connect became imminent. Bear in mind that true integrations had never existed before, so the thought behind integrating existing in a monolithic paradigm.
The spirit of SOAP was simple: when you build an app, build it in a way that you can provide services to others. It was a high-level approach to connect core services to the rest of a technology ecosystem.
Like any legacy technology, SOAP still exists today. It served a fantastic purpose at the time of its conception, but the ever-evolving nature of technological progress has made it difficult to efficiently work with by today’s standards.
gRPC (Google Remote Procedure Call)
gRPC is Google’s way of connecting software. At a high level, Google created their own mechanism that replaces rest; much the same way that Facebook created GraphQL.
To this extent, these API technology solutions are born in a specific need. While Facebook wanted a graph of data across all of their applications, Google was seeking a solution that allowed for the movement of massive amounts of data efficiently.
While this makes sense for Google, most API users only need to move data on a transactional basis. This means that they do not require the need for a highly efficient API technologies. For perspective, most JSON/REST API calls will execute in 5-10 milliseconds. gRPC increases this speed, though most use cases do not need this.
Schema
JSON schema (JavaScript Object Notation)
JSON is the most widely adopted schema for modern-day APIs. In fact, the early example of “what an API looks like” in this article was a piece of a JSON file.
The syntax this schema is intuitive and exhaustive. Plain and simple: JSON is today’s current standard for APIs. While there is the exploration of new API technologies like GraphQL, you can rest assured that most everyone will be referring to JSON when referring to an API’s schema.
GraphQL SDL (GraphQL Schema Definition Language)
GraphQL brought a unique and relevant approach to the way that API publishers make their software available and how consumers take it in. Part of that involved a schema.
By defining and communicating your API technologies in GraphQL’s schema definition language, you have the ability to utilize the technology’s power as a query language. Large technology providers are beginning to offer their API through GraphQL. At this point, it stands as an additional channel to cater to API consumers.
XSD for XML (Schema Definition for Extensible Markup Language)
XML’s query language saw its rise before JSON. XML serves its purpose and is still more than adequate for the communication with older APIs. Punchline: depending on the tools you are using and software you are connecting, XML is very usable. That said, APIs developed today typically opt for using JSON as opposed to XML as a schema.
API Specifications
Open API
The OpenAPI Specification (OAS) is an API description format for REST APIs. It defines an interface which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. At a high level, OAS describes (1) available endpoints, (2) available operations within those endpoints (GET, POST, etc.), and (3) authentication methods.
In terms of schema, OpenAPI uses JSON with YAML compatibility. Swagger is commonly used with OpenAPI Spec. At Aloi, we use OpenAPI specs to define the APIs deployed on our platform.
API Blueprint
API Blueprint is an open sourced specification with a dependence on markdown. It also dismisses the need for JSON or YAML. This specification would likely appeal to developers that focus on C++ through Node.js and C# implementations, as opposed to Java and javascript which are utilized by Open API and RAML.
API Blueprint requires third party server code, making it harder to get started with than other specifications. The API Blueprint community is smaller than that of other specifications, but every language has its purposes.
Apiary is the most common editor for API Blueprint.
RAML (RESTful API Modeling Language)
RAML is strictly YAML in representation
Because of the way RAML is designed, it can support REST API documentation in addition to documentation for APIs that don’t precisely or strictly adhere to REST standards. This includes those utilizing other design architectures like SOAP and RPC.
Contrary to Swagger, which explains the functionality of an API through models and submodels, RAML specifically annotates and describes function methodology through nested resources and sub-resources. This, aesthetically, is far more oriented towards hierarchical function understanding than simple “cause and effect” understanding.
RAML is very much a hierarchical style format, which is one of the many reasons it is such an excellent planning tool. By visualizing the cause and effect of requests to the API, as well as documenting specific examples of what return can be expected, APIs can either be documented or planned with incredible granularity.