1. apidoc
2. documenting APIs
3. API glossary and resources

API glossary

A

API

Application Programming Interface. Enables different systems to interact with each other programmatically. Two types of APIs are REST APIs (web APIs) and native-library APIs. See What is a REST API?

API Console

Renders an interactive display for the RAML spec. Similar to Swagger UI, but for RAML. See github.com/mulesoft/api-console.

APIMATIC

Supports most REST API description formats (OpenAPI, RAML, API Blueprint, etc.) and provides SDK code generation, conversions from one spec format to another, and many more services. APIMATIC “lets you define APIs and generate SDKs for more than 10 languages.” For example, you can automatically convert Swagger 2.0 to 3.0 using the API Transformer service on this site. See https://apimatic.io/ and read their documentation.

API Transformer

A cross-platform service provided by APIMATIC that will automatically convert your specification document from one format or version to another. See apimatic.io/transformer.

Apiary

Platform that supports the full life-cycle of API design, development, and deployment. For interactive documentation, Apiary supports the API Blueprint specification, which similar to OpenAPI or RAML but includes more Markdown elements. It also supports the OpenAPI specification now too. See apiary.io.

API Blueprint

The API Blueprint spec is an alternative specification to OpenAPI or RAML. API Blueprint is written in a Markdown-flavored syntax. See API Blueprint in this course, or go to API Blueprint’s homepage to learn more.

Apigee

Similar to Apiary, Apigee provides services for you to manage the whole lifecycle of your API. Specifically, Apigee lets you “manage API complexity and risk in a multi- and hybrid-cloud world by ensuring security, visibility, and performance across the entire API landscape.” Supports the OpenAPI spec. See apigee.com.

Asciidoc

A lightweight text format that provides more semantic features than Markdown. Used in some static site generators, such as Asciidoctor or Nanoc. See http://asciidoc.org/.

B

branch

In Git, 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. If you’re editing documentation in a code repository, developers will probably have you work in a branch to make your edits. The developers will then either merge your branch into the master when ready, or you might submit a pull request to merge your branch into the master. See git-branch.

C

clone

In Git, clone is the command used to copy a repository in a way that keeps it linked to the original. The first step in working with any repository is to clone the repo locally. Git is a distributed version control system, so everyone working in it has a local copy (clone) on their machines. The central repository is referred to as the origin. Each user can pull updates from origin and push updates to origin. See git-clone.

commit

In Git, 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. You commit your changes before pulling from origin or before merging your branch within another branch. See git-commit.

CRUD

Create, Read, Update, Delete. These four programming operations are often compared to POST, GET, PUT, and DELETE with REST API operations.

curl

A command line utility often used to interact with REST API endpoints. Used in documentation for request code samples. curl is usually the default format used to display requests in API documentation. See curl. Also written as cURL. See Make a curl call and Understand curl more.

E

endpoints and methods

The endpoints indicate how you access the resource, while the method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource.

The same resource usually has a variety of related endpoints, each with different paths and methods but returning different information about the same resource. Endpoints usually have brief descriptions similar to the overall resource description but shorter. Also, the endpoint shows the end path of a resource URL only, not the base path common to all endpoints. See Endpoints and methods.

G

Git

Distributed version control system commonly used when interacting with code. GitHub uses Git, as does BitBucket and other version control platforms. Learning Git is essential for working with developer documentation, since this is the most common way developers share, review, collaborate, and distribute code. See https://git-scm.com/.

GitHub

A platform for managing Git repositories. Used for most open-source projects. You can also publish documentation using GitHub, either by simply uploading your non-binary text files to the repo, or by auto-building your Jekyll site with GitHub Pages, or by using the built-in GitHub wiki. See GitHub wikis in this course as well as on pages.github.com/.

Git repo

In Git, a repo (short for repository) stores your project’s code. Usually, you only store non-binary (human-readable) text files in a repo, because Git can run diffs on text files and show you what has changed.

H

HAT

Help Authoring Tool. Refers to the traditional help authoring tools (RoboHelp, Flare, Author-it, etc.) used by technical writers for documentation. Tooling for API docs tends to use docs-as-code tools more than HATs.

HATEOS

Stands for Hypermedia as the Engine of Application State. Hypermedia is one of the characteristics of REST that is often overlooked or missing from REST APIs. In API responses, responses that span multiple pages should provide links for users to page to the other items. See HATEOS.

Header parameters

Parameters that are included in the request header, usually related to authorization.

Hugo

A static site generator that uses the Go programming language as its base. Along with Jekyll, Hugo is among the top 5 most popular static site generators. Hugo is probably the fastest site generator available. Speed matters as you scale the number of documents in your project beyond several hundred. See https://gohugo.io/. For more about static site generators, see Static site generators.

J

JSON

JavaScript Object Notation. A lightweight syntax containing objects and arrays, usually used (instead of XML) to return information from a REST API. See Analyze the JSON response in this course and http://www.json.org/.

M

Mercurial

A distributed revision control system, similar to Git but not as popular. See https://www.mercurial-scm.org/.

method

The allowed operation with a resource in terms of GET, POST, PUT, DELETE, and so on. These operations determine whether you’re reading information, creating new information, updating existing information, or deleting information. See Endpoints and methods.

Mulesoft

Similar to Apiary or Apigee, Mulesoft provides an end-to-end platform for designing, developing, and distributing your APIs. For documentation, Mulesoft supports RAML. See https://www.mulesoft.com/.

O

OAS

Abbreviation for OpenAPI specification.

OpenAPI

The official name for the OpenAPI specification. The OpenAPI specification provides a set of properties that can be used to describe your REST API. When valid, the specification document can be used to create interactive documentation, generate client SDKs, run unit tests, and more. You can read the specification details on GitHub at https://github.com/OAI/OpenAPI-Specification. Under the Open API Initiative with the Linux Foundation, the OpenAPI specification aims to be vendor neutral (many companies steer its development, not just one). See Introduction to the OpenAPI specification.

OpenAPI contract

Synonym for OpenAPI specification document.

OpenAPI specification document

The file (either in YAML or JSON syntax) that describes your REST API. Follows the OpenAPI specification format. See https://www.openapis.org/. See also OpenAPI 3.0 tutorial.

OpenAPI Initiative

The governing body that directs the OpenAPI specification. Backed by the Linux Foundation. See https://www.openapis.org/.

P

parameters

Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response. There are several types of parameters: header parameters, path parameters, and query string parameters. Request bodies are closely similar to parameters but are not technically a parameter.

The different types of parameters are often documented in separate groups on the same page. Not all endpoints contain each type of parameter. See Parameters for more details.

Path parameters

Parameters that appear within the path of the endpoint, before the query string (?). Path parameters are usually set off within curly braces. See Parameters for more details.

Pelican

A static site generator based on Python. See https://github.com/getpelican/pelican. For more about static site generators, see Static site generators.

Perforce

Revision control system often used before Git became popular. Often configured as a centralized repository instead of a distributed repository. See Perforce.

pull

In Git, when you pull from origin (the master location where you cloned the repo), you get the latest updates from origin onto your local system. When you run git pull, Git tries to automatically merge the updates from origin into your copy. If the merge cannot happen automatically, you might see merge conflicts. See git-pull.

Pull Request

A request from an outside contributor to merge a cloned branch back into the master branch. The pull request workflow is commonly used with open-source projects because developers outside the team will not usually have contributor rights to merge updates into the repository. GitHub provides a user-friendly interface for making and processing pull requests. See Pull Requests.

push

In Git, when you want to update the origin with the latest updates from your local copy, you run git push. Your updates will bring origin back into sync with your local copy. See https://git-scm.com/docs/git-push.

Q

Query string parameters

Parameters that appear in the query string of the endpoint, after the ?. See Parameters for more details.

R

RAML

Stands for REST API Modeling Language and is similar to OpenAPI specifications. RAML is backed by Mulesoft, a commercial API company, and uses a more YAML-based syntax in the specification. See RAML tutorial in this course or RAML.

RAML Console

In Mulesoft, the RAML Console is where you design your RAML spec. Similar to the Swagger Editor for the OpenAPI spec.

Repo

A tool for consolidating and managing many smaller repos with one system. See git-repo. For the definition of a Git repository, see Git repo.

request

The way information is returned from an API. In a request, the client provides a resource URL with the proper authorization to an API server. The API returns a response with the information requested. See Request example for more details.

request body

A block of information, usually JSON, included in the request body, often used with CREATE and PUT methods. See Parameters for more details.

response example and schema

The response example shows a sample response from the request example; the response schema defines all possible elements in the response. The response example is not comprehensive of all parameter configurations or operations, but it should correspond with the parameters passed in the request example. The response lets developers know if the resource contains the information they want, the format, and how that information is structured and labeled.

The description of the response is known as the response schema. The response schema documents the response in a more comprehensive, general way, listing each property that could possibly be returned, what each property contains, the data format of the values, the structure, and other details. See Response example and schema for details.

resource description

“Resources” refers to the information returned by an API. Most APIs have various categories of information, or various resources, that can be returned.

The resource description is brief (1-3 sentences) and usually starts with a verb. Resources usually have various endpoints to access the resource and multiple methods for each endpoint. On the same page, you usually have a general resource described along with a number of endpoints for accessing the resource, also described. See Resource description for more details.

response

The information returned by an API after a request is made. Responses are usually in either JSON or XML format. See Response example and schema for details.

response example and schema

The response example shows a sample response from the request example; the response schema defines all possible elements in the response. The response example is not comprehensive of all parameter configurations or operations, but it should correspond with the parameters passed in the request example. The response lets developers know if the resource contains the information they want, the format, and how that information is structured and labeled.

The description of the response is known as the response schema. The response schema documents the response in a more comprehensive, general way, listing each property that could possibly be returned, what each property contains, the data format of the values, the structure, and other details. See Response example and schema for details.

REST API

Stands for Representational State Transfer. Uses web protocols (HTTP) to make requests and provide responses in a language agnostic way, meaning that users can choose whatever programming language they want to make the calls. See What is a REST API? for more details.

S

SDK

Software development kit. Developers often create an SDK to accompany a REST API. The SDK helps developers implement the API using a specific language, such as Java or PHP. See SDKs for more details.

Smartbear

The company that maintains and develops the Swagger tooling — Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. See Smartbear.

Sphinx

A static site generator developed for managing documentation for Python. Sphinx is the most documentation-oriented static site generator available and includes many robust features – such as search, sidebar navigation, semantic markup, managed links – that other static site generators lack. Based on Python. See staticgen.com/sphinx for high-level details. For more about static site generators, see Static site generators.

Static site generator

A breed of website compilers that package up a group of files (usually written in Markdown) and make them into a website. There are more than 350 different static site generators. See Jekyll in this course for a deep-dive into the most popular static site generator, or Staticgen for a list of all static site generators. See Static site generators for a deep-dive into this topic.

Stoplight

Provides a platform with visual modeling tools to create an OpenAPI document for your API — without requiring you to know the OpenAPI spec details or code the spec line by line. See http://stoplight.io/ for more information. See Stoplight — visual modeling tools for creating your OpenAPI spec for more information.

Swagger

Refers to API tooling related to the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear. For more tools, see Swagger Tools. “Swagger” was the original name of the OpenAPI spec, but the name was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. People sometimes refer to both names interchangeably (especially on older web pages), but “OpenAPI” is how the spec should be referred to. For more on naming conventions between OpenAPI and Swagger, see What Is the Difference Between Swagger and OpenAPI?.

Swagger Codegen

Generates client SDK code for a lot of different platforms (such as Java, JavaScript, Scala, Python, PHP, Ruby, Scala, and more). The client SDK code helps developers integrate your API on a specific platform and provides for more robust implementations that might include more scaling, threading, and other necessary code. In general, SDKs are toolkits for implementing the requests made with an API. Swagger Codegen generates the client SDKs in nearly every programming language. See Swagger Codegen for more information. See also SDKs.

Swagger Editor

An online editor that validates your OpenAPI document against the rules of the OpenAPI specification. The Swagger Editor will flag errors and give you formatting tips. See Swagger Editor.

Swagger UI

An open-source web framework (on GitHub) that parses an OpenAPI specification document and generates an interactive documentation website. Swagger UI is the tool that transforms your spec into the Petstore-like site.

SwaggerHub

A site developed by Smartbear to help teams collaborate around the OpenAPI spec. In addition to generating interactive documentation from SwaggerHub, you can generate many client and server SDKs and other services. See Manage Swagger Projects with SwaggerHub.

V

VCS

Stands for version control system. Git and Mercurial are examples.

version control system

A system for managing code that relies on snapshots that store content at specific states. Enables you to revert to previous states, branch the code into different versions, and more. See About Version Control in Git. See Version Control Systems for more information.

Y

YAML

Recursive acronym for “YAML Ain’t No Markup Language.” A human-readable, space-sensitive syntax used in the OpenAPI specification document. See More About YAML.