The tech space is constantly evolving. Thus staying up to date with the latest terminologies is essential. If you’re just getting into APIs, these are some of the most commonly used terms that every API technologist should know.

API

An Application Programming Interface (API) is a system of internal code and associated endpoints that allows connection and communication between two systems. APIs can exist in various forms. For example, computers utilize APIs to bridge communication between different internal systems to translate graphic rendering requests to discrete processors. In the context of the world wide web and the internet, APIs connect servers and data systems to allow for retrieval, permutation, and alteration.

Call/Request

When an end-user interacts with an API to accomplish a task, that interaction is facilitated by an API call, also called a request. These actions are done upon an endpoint which then filters the request or calls to the right aspect of the API and its associated data set.

Endpoint

Endpoints are defined URLs/URIs that are associated with a specific action or function of the core API. For instance, if a weather API can serve data for a specific area as defined by coordinates, that would likely exist as a particular endpoint — other functions would also exist as their own discrete endpoints. Endpoints are typically limited to a single function, though variations of that function can also exist on that endpoint awaiting activation through additional passed parameters.

Parameters

Parameters are variables in the endpoint call or request that allow for a permutation to be performed between the request and the output. For instance, an API might provide data output for a request in three different formats, and in order to choose a specific format, a parameter might have to be provided.

Headers

Headers are elements of the API request and response that are used to pass additional information. This additional information can be of a wide variety, though the most typical information use case is to pass metadata and context for the content itself.

External and Internal

An external API is created for external use by the public and is designed to face a broad userbase. Internal APIs are intended for internal use by an organization or collection of users, and are not meant to be accessed by a wider userbase or audience. There are also partner APIs and other emerging styles.

Implementation

An implementation is the sum-total deployment of the codebase and its associated data to create a total solution to a specific problem. Developers will often refer to their particular solution as an “implementation.” If two implementations are almost identical with only a minor change between them, they are still considered to be two separate and distinct implementations.

Client

APIs tend to be discussed within the context of a client-server relationship. Clients are the devices or systems that communicate with the server and are typically the entity making requests on behalf of end-users. Common clients include personal computers and mobile phones.

Server

APIs tend to be discussed within the context of a client-server relationship. Servers are the systems that respond to client requests by offering the transformed and delivered data output. Servers are separate from the end-user and typically represent the data storage and manipulation side of the request flow.

Technical Terms

HTTP Methods

HTTP Methods are the standard interaction methods as codified by the HTTP, or HyperText Transfer Protocol, standard. These methods are commonly used to interact with data utilizing APIs. The most common methods are shown below.

• GET is used to retrieve information utilizing a specific URI. GET should only retrieve data and should not change the data in any way.
• POST is used to send data to the server. While it can function similarly to GET, POST is allowed to make changes to the data.
• PUT is used to replace current representations of the resource with a new representation. In essence, it’s used to replace data with new data.
• DELETE is used, interestingly enough, to delete the current representations of data.

Keys

API Keys are specific strings of data that are used to identify a user or application and provide authentication. Keys are typically used to secure an API, and are widely used in common applications like OAuth to control the flow of information and function.

Cache

An API cache is the area in an API system that stores data that has been requested by users for additional access in the future. Cached data is often much less intensive and much quicker to serve compared to non-cached data, and if a request is often made for a specific point of data, especially if that data is not commonly updated, caching is an optimal solution.

JSON

JSON, or JavaScript Object Notation, is a data-interchange format developed from a subset of JavaScript. JSON is very lightweight, but it gains this through simplicity, meaning that it is often difficult to represent extremely complex structures. JSON is language-agnostic, but much of its form and function is similar to the C family of languages, making it a popular format when working with C-based applications.

XML

XML, or Extensible Markup Language, is a markup language and file format system for the storage and transmission of data. It utilizes a native encoding ruleset definition system to create a format that is both human and machine-readable. XML is very verbose, but what it loses in efficiency it gains in its ability to represent complex structures as arbitrarily defined by the user.

GraphQL

GraphQL is a query language that has been widely adopted as a way to provide custom form responses. It allows requestors to define the structure and form of the resultant output of their request, which allows for specific form and function to be delivered according to the needs of the client.

Business and Developer Terminology

Framework

Frameworks are the collection of libraries, instructions, and APIs that form a structural system underlying a specific development or implementation. The framework represents a collective solution from which APIs can pull resources in order to accomplish a specific goal.

Schema

Schemas are metadata systems that structure the systems and data underlying the API. Schemas are core to API design and are typically representative of a specific paradigm or mode of delivery and consumption.

Monetization

Monetization is the process of leveraging the value in an API to generate revenue. This can be done in a variety of ways, including providing free trials that result in charges for continued usage (freemium), charges for the amount of utilization (rate charging), and other models. Monetization is often a balancing act between providing the highest amount of initial utility to the end-user while creating a potential revenue source to fund continued development and operation.

API-as-a-Product

API-as-a-Product is the term to describe a business model wherein the API is the core product offering. An API-as-a-Product typically monetizes a niche service or functionality, allowing the consuming party to outsource a portion of their IT in a reusable manner. The API-as-a-Product trend has peaked in recent years as businesses begin to realize the value of API-first offerings.

Production Environment

The production environment of an API is the environment that reflects the actual use case of the end-user. This is different from a testing environment or mock environment in that the application runs in real-time in real-world conditions. A production environment is what the API consumer will interact with and may not always match how the service is documented — a reality known by Hyrum’s Law.

SDK

A Software Development Kit (SDK) is a toolbox of practices, methods, code samples, documentation, implementation guidelines, and build instructions to create applications on a specific platform or system. SDKs enable developers to develop within a narrow set of guidelines and often cater to a particular programming language. As such, SDKs vary from platform to platform.

Lifecycle

The lifecycle of an API is the time from its creation to its ultimate obsolescence, or “sunsetting“. This period may include long-term updates past its obsolescence data, and long-term support may sometimes be considered separate from the initial active lifecycle (in these cases, variations on terms such as “long-term support” or “end of lifecycle support” are common).

SDLC

SDLC, or Software Development Lifecycle, is the overall process of ideating, planning, developing, testing, and deploying a specific software development. SDLC is a specific process, but it can be deployed through several different models, including waterfall, iterative, agile, and others. The ultimate goal of SDLC is to deliver the highest quality solution with the lowest cost in terms of money and time.

Architectures, Protocols, and Paradigms

REST

Representation State Transfer (REST) is an architectural paradigm for API development and design that was created by Roy Fielding as part of his dissertation called “Architectural Styles and the Design of Network-based Software Architectures”. There are a variety of considerations that must be met for an API to be considered RESTful, but generally speaking, a RESTful API will be stateless, meaning that the server will not store data concerning the client session on the server-side.

SOAP

Simple Object Access Protocol (SOAP) is a protocol designed to exchange data between applications. SOAP uses XML as the format for its envelope, header, and body elements, and Web Services Description Language (WSDL) as the format for the message schemas. SOAP is highly structured, and like REST, is stateless. Unlike REST, however, SOAP can be made to be stateful, making it more appropriate for use cases in which state must be preserved.

Monolith

The traditional way of developing software systems was to create everything as a single entity, packaging functions with datasets into a monolithic structure. While this is still standard in some use cases, monolithic development typically means that small changes must have an effect across the entire codebase, increasing development costs both monetarily and in terms of time. Monolithic development still has its place, especially when the software must be highly secure or is developed for internal use cases.

Microservices

Microservice-based design, also known as the microservices architecture, has become a nearly ubiquitous development model in the API space. In contrast to the monolith, microservices break up every group of functions and their associated data sets into their own independent and loosely-coupled applications. A microservice-centric solution might have the user management, requests facilitation, database and storage, and transformation functions all separated across different applications. This makes development somewhat more complex but allows for changes to be made to a system while other components remain unchanged.

Push

“Push” is an API paradigm in which content is “pushed” to the user without a direct request from the end-user. This is most often used in the context of subscription, wherein a user requests updates at a later date, and the API “pushes” to the subscribed user when something about the data is altered or updated.

Pull

“Pull” is an API paradigm in which content is “pulled” as the request of a direct user request. This is the more traditional experience for the end-user who is submitting API calls over the internet. When users discuss using endpoints to make calls, they are typically referring to this paradigm.

Webhook

Webhooks are APIs oriented behind a Push design paradigm. Webhooks automatically push real-time data to other applications and APIs utilizing various technical solutions, allowing immediate data availability for a variety of transformative functions.

30 Terms You Should Know

There you have it — 30 terms you should know about APIs. But if you can believe it, these only present the tip of the iceberg. There are plenty more nuances and specific terminologies to understand as we explore the world of APIs! Did we miss out on any important ones? Let us know in the comments below.