The API industry can be confusing. Here's a breakdown of all lingo, verbiage, and relevant terms that you need to know when it comes to designing, documenting, or developing an API program.
API stands for “application programming interface.” More simply, it is a collection of definitions, instructions, and protocols for building and connecting software. An API is the connection between two programs that exposes the select business or operational value of one to the other.
An API architect typically performs a high-level project management role within a software development team or organization. Their responsibilities can be extensive and diverse, and a good API architect must combine advanced technical skills with business knowledge and a focus on communication and collaboration.
API-as-a-Product is an established and increasingly popular software development concept. But what is API-as-a-Product? What are some ways an organization can monetize an API?Like Software-as-a-Service, an API-as-a-Product exposes and monetizes an organization’s unique functionality or services. These services are typically delivered over HTTP.
In this model, the API is at the core of the business’s value. For API-as-a-Products, the API is not only the method of delivery; it is what is being delivered.
A high-level description for web APIs, focused on collaboration and governance. Also a specification standard, created by Apiary, acquired by Oracle.
API design is the collection of planning and architectural decisions you make when building an API driven by the business objectives. Your basic API design influences how well developers are able to consume it and even how they use it. Just like website design or product design, API design informs the user experience. Good API design principles meet initial expectations and continue to behave consistently and predictably.
The process of creating your actual API including planning, testing, and automation that can support your API development.
An API Management tool that sits between a client and a collection of backend services -- acts as a reverse proxy to accept all API calls, aggregate the various services required to fulfill them, then return the appropriate result.
A unique identifier to authenticate a user/project to an API.
Describe data structures, typically in request/response of an API. Models may also be common/shared across many APIs (for example, an Address model). Models may contain schema, examples and extensions, in specifications like OpenAPI.
The practice of monitoring APIs, mostly in production to gain visibility into performance, availability, and functional correctness.
An API program leader is often the head of the API program within an organization, responsible for scaling the entire API program, creating the vision, goals, and strategy behind the API program. They can be supported by other developers, business leaders, product managers, architects, and technical writers.
Note that in smaller organizations, this may be a less formal role.
A tool that developers can use with their apps (in any language) to define external identity providers + integrations, it is basically an authentication and authorization platform for your application.
A Microsoft product that provides version control, reporting, management, testing for API lifecycles and enables DevOps capabilities. Stoplight now integrates with ADOS for improved security, consistency, and scalability of your API program.
A Git-based version control platform by Atlassian, it's used for code hosting and as a collaboration tool, and is built for teams.
A branch is a copy of the repository that is often used for developing new features. Usually, you work in branches and then merge the branch into the master branch when you’re ready to publish.
This stands for Continuous Delivery/Deployment. Continuous Delivery is the frequent shipping of code to a given environment (such as test or production) via manual release. Continuous Deployment is the automated release of code to a production environment.
This stands for Continuous Integration. Continuous integration is the practice of integrating code as soon as it's ready, rather than the larger risk of waiting to deploy large merge sets.
In Git, clone is the command used to copy a repository in a way that keeps it linked to the original.
Where you work seamlessly on your API design by bringing all internal and external stakeholders in a single place with flexible roles and permissions.
A commit is when you take a snapshot of your changes to the repo. Git saves the commit as a snapshot in time that you can revert to later if needed.
Create, Read, Update, and Delete (CRUD) are the four basic operations that resource-oriented APIs are generally expected to perform functions that models should be able to perform. In computer programming, they are also the four basic operations of persistent storage.
CRUD is also sometimes used to describe user interface conventions that facilitate viewing, searching, and changing information using computer-based forms and reports.
Cascading Style Sheets that allow you to edit the appearance of your HTML files (websites)
In an API design-first development process, API architects begin with writing a specification and engaging all stakeholders in the process from its inception. The result of a design-first process is an API product that is comprehensive, consistent, and understandable by both collaborators and machines.
When multiple developers are working on the API and when multiple teams are creating multiple APIs, quality control can suddenly feel more important. Incorporating regular reviews of your API design will help ensure that there are no consistency issues, breaking changes, user issues, or adoption troubles later down the line. Review early and often!
Also called a computer programmer, software developer, software engineer, or a programmer. This is a person who creates computer programs, often for larger computer software.
A web interface for a set of APIs, SDKs, or other interactive tools and their various stakeholders.
API docs, or API description documents, are the collection of references, tutorials, and examples that help developers use your API. Your API’s documentation is the primary resource for explaining what is possible with your API and how to get started. It also serves as a place for developers to return with questions about syntax or functionality. The best API docs have these answers hence why it is so important that you document your API.
An open-source documentation tool by Stoplight that helps you build highly customized, interactive, web component-based API Docs with embeddable web components generated from OpenAPI documents.
Help internal and external users discover, learn, and integrate with your API quickly by publishing interactive documentation, tutorials, and code samples that are always up to date.
The URI/URL where API/service can be accessed by a client application. Caveat: 'Endpoint' is language carried over from the SOAP/SOA era, a more appropriate term for REST/HTTP APIs is 'operation.
Retrieve data from a specified resource.
Version control system for tracking changes in source code during software dev
Git is free and open source software for distributed version control: tracking changes in any set of files, usually used for coordinating work among programmers collaboratively developing source code during software development.
A Git workflow is a recipe or recommendation for how to use Git to accomplish work in a consistent and productive manner. Git workflows encourage developers and DevOps teams to leverage Git effectively and consistently. Git offers a lot of flexibility in how users manage changes.
Github is a version control platform for software development and version control using Git. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous integration, and wikis for every project.
Gitlab is an open-core company that provides GitLab, a DevOps software package that combines the ability to develop, secure, and operate software in a single application.
API governance is the of applying rules and policies to your APIs. You create processes that standardize various aspects of your APIs, such as: Descriptions, Contracts, Designs, Protocols, and Quality Reviews. This standardization helps ensure that all your APIs remain consistent even when different developers design and build them. An effective API governance program helps organizations ensure that every API is high-quality and discoverable—whether they create a few APIs or a few thousand.
An open-source data query and manipulation language for APIs, developed internally by Facebook and released to public in 2015, allows you to get many resources in a single request. GraphQL is an open-source query and manipulation language with a heavy focus on client developer experience.
A programming language that allows you to create dynamically updating content, control multimedia, animate images on a website.
JavaScript Object Notation, a way to express how a client should request that resources be fetched or modified and how a server should response to those requests, data stored in name/value pairs, records separated by commas, field names & strings are wrapped by double quotes
Used to design and model data structures for an API. Use the JSON Schema Editor to create request and response bodies for an endpoint, as well as data models that can be used across one or more APIs.
Linting is a process by a linter program that analyzes source code in a particular programming language and flag potential problems in your API design. (e.g. Spectral is often used for linting OpenAPI, and other JSON-based specifications.)
A lightweight language to format richer text generally for ReadMe files that is device diagnostic. Markdown is an easy-to-use markup language that is used with plain text to add formatting elements (headings, bulleted lists, URLs) to plain text without the use of a formal text editor or the use of HTML tags.
Markup refers to the sequence of characters or other symbols that you insert at certain places in a text or word processing file to indicate how the file should look when it is printed or displayed or to describe the document's logical structure. The markup indicators are often called "tags."
Microservices are a dev architecture where every feature is its own app (API), however there's no industry-wide universal definition of microservices. Microservices are small, autonomous services that work together, and some companies define microservices as an architectural pattern used to build and structure applications as a collection of loosely coupled, small services.
Each service is treated separately and can be reused within the company or externally by third-party developers. A microservices architecture can consist of dozens, hundreds, even thousands of individual services. And because each service is autonomous, you can add new features and fix problems without the risk of breaking the entire application.
A mock API server is useful during development and testing when live data is either unavailable or unreliable. While designing an API, you can use mock APIs to work concurrently on the front and back-end, as well as to gather feedback from developers. You can using mocking to visualize and get feedback on your API designs before spending time on development. Mocking may also apply to stubbing, simulation, and virtualization.
A dev architecture where all features are part of one main whole and are contained in a single application architecture (in contrast with microservices and/or distributed system).
Originally Swagger 2.0, (Derived from Swagger 1.0 (as originally defined by SmartBear), OAS2 was the first version of OpenAPI as a Linux Foundation project), an update to the spec that helped devs define APIs over the past few years. Can define only 1 endpoint (compared to OAS3, which allows multiple).
Compared to Swagger 2.0, OAS3 comes in more modular and reusable when it comes to describing the request response models and underlying security info.
OAuth is a way to provide access/security without giving away a password (uses access tokens instead). It's a technological standard that allows you to share information between services without exposing your password. It's a widely-adopted standard that's used by developers of websites and apps, and you probably use services every day that utilize OAuth.
Installed and deployed on a company's own servers/cloud (rather than the public cloud).
OpenAPI is open API is a valuable type of technology for developers. It provides standards for how software programs communicate with each other. With OpenAPI, developers have to write less code to make different software programs work together seamlessly.
OpenAPI is first meant to be interpreted by machines, but there are many ways it can be used by people. Once you have a complete description of how a REST API works, much of the way engineers work with APIs can be streamlined.
A specification to help developers create standardized APIs that can communicate with each other more easily. To adopt the OpenAPI Specification, you create a document that defines your REST API or HTTP API in OpenAPI’s standard format. As an open-source project that is language agnostic and vendor-neutral, the has been widely adopted by the industry and is supported by a range of open source and proprietary tools.
An operation, in REST, is the combination of HTTP method + URI, i.e. 'GET /products'. A group of operations in a resource-oriented API design will often use a CRUDL pattern. "Endpoint" is a SOAP-based term that is often used as a synonym for "Operation."
Prism is Stoplight's open-source HTTP mock server that can mimic your API's behavior as if you already built it. Mock HTTP servers are generated from your OpenAPI v2/v3 (formerly known as Swagger) documents. Prism validates both request and response data. If you have an invalid example in the specification, Prism will let you know; if your request is not compliant with the rules of your API specification, Prism will return an error message.
Also can be referred to as an API product manager, it is a role that is responsible for the development of products for an organization. Product managers own the product strategy behind a product, specify its functional requirements, and manage feature releases.
RAML is the RESTful API Modeling Language and is built on top of YAML. That means at-a-glance, they look similar. In fact, all RAML is YAML, but the reverse is not true.
As the acronym suggests, RAML is focused on modeling (or designing) APIs. At its simplest, RAML can be used to describe an API’s endpoints.
REpresentational State Transfer, an architectural style for designing networked applications. REST is a very popular web API architecture. To be a REST API, an API must adhere to certain architectural constraints, or principles, including:
Software as a Service, a subscription based software hosted on the cloud
Security Assertion Markup Language, you can use one set of credentials to log into many different websites (passes authorization credentials to service providers)
A schema is metadata that tells us how our data is structured. In Stoplight, the JSON Schema Editor provides an easy way to build OpenAPI Schema Objects.
Simple Object Access Protocol, uses XML data to declare request and response messages. Similarly to REST APIs, SOAP APIs connect 2 apps via server-side data, use HTTP protocols and operations. The SOAP specification includes:
A folder that tracks all changes (version control) of your projects. A software repository, or repo for short, is a storage location for software packages. Often a table of contents is also stored, along with metadata.
An API specification provides a basic understanding of how an API will behave and how it will links with other APIs. It covers API functions and the results to expect you can expect when using that API. An example is the OpenAPI Specification, which is encompasses a machine-readable interface of files for describing, producing, consuming, and visualizing RESTful web services.
Spectral is an open-source linting tool by Stoplight for JSON/YAML linting. It allows you to create style guides for your structured data; things like OpenAPI/AsyncAPI/RAML descriptions, Kubernetes config, GitHub Actions, you name it, Spectral can help you lint it.
Stoplight is an API design, development, and documentation platform that enables consistency, reusability, and quality
A doc that helps everyone adhere to basic API design patterns and conventions, such as Spectral (our open-source linting tool), or the capability offered in Stoplight Platform.
A tooling ecosystem for developing APIs w/ OAS, describing RESTful APIs in JSON language.
Also called documentation writers, a technical writer is a professional information communicator whose task is to transfer information between two or more parties, through any medium that best facilitates the transfer and comprehension of the information.
API testing is where you test different components of the API to ensure it will work. As part of integration testing to determine if they meet expectations for functionality, reliability, performance, and security. Usually, this consists of making requests to a single or multiple API endpoints and then validating a response.
Testing can be performance, security, functional correctness, or status related depending on what it is your testing. Not to be confused with mocking, which is where you build a mock API server to see how the API will perform.
VCS stands for Version Control System which is a class of systems responsible for managing changes to computer programs, big web sites, docs, or large loads of information.
YAML, a superset of JSON, is a human friendly data serialization standard for all programming languages. It is commonly used for configuration files and in applications where data is being stored or transmitted. Originally, it stood for Yet Another Markup Language, now it's known as "Ain’t Markup Language."
