Glossary – API Doc Example

The following table shows some of the terms and definitions used in Representational State Transfer (REST) service calls.

API Term	Dscription
Array	A data structure that can contain a group of elements. The elements are usually all the same data type, such as character or Boolean.
Authentication	Part of API security, authentication identifies the authorized user.
Authorization	Part of API security, authorization grants access to users who may be required to apply for access, and the authorized user will be granted keys or a token.
cURL (or curl)	A command-line tool providing a language-independent format for showing Hypertext Transfer Protocol (HTTP) requests and responses, including any headers and other parameters. Users of an API can translate cURL into whatever front-end language(s) they are working with.
Endpoint	The URL that makes up part of an API. This URL is indicated after the base URL and points to the requested API functionality. KJ (suggestions on this?): In an API request, an endpoint indicates the specific data that is required to get an accurate response. Example: to return a list of physicians in your area, you must pass a city name or a ZIP code endpoint in your request.
Host	The header that contains the domain name of the request URL.
HTTP method	The actions performed by REST API services. The primary methods used in REST service calls are as follows:Get: Retrieve data. Post: Create data. Put: Update data. Delete: Delete data.
JSON (JavaScript Object Notation)	JSON is a common data format used for API requests and responses. The primary parts included in the JSON format include: Key-value pair: Key: A string enclosed in quotation marks being the attribute of a value. Value: The value of an attribute. It can be a string, Boolean expression, array, number, or an object. Example: [“A”, “B”, “C”]. Integer and Boolean values do not require quotes.
	Array: An array is one of two types of JSON coding structures—a list of items grouped by brackets [ ]. Example: [“A”, “B”, “C”]. Integer and Boolean values do not require quotes.
	Object: An object is one of two types of JSON coding structures—a collection of key-value pairs grouped by curly braces { }. Example: { “city”:”Phoenix”, “weather”:”freakin hot”, “wind”}
Parameter	REST services use the following parameter types: Header: Path: Variables of a URL path denoted by curly braces {}. A URL path may have several path parameters. Query: Doug R_Query String: parameters following the question mark (question) in a resource’s endpoint. They are concatenated, in any order, with each parameter separated by an ampersand (&). Request body: Contains the data the client wants to send to the server.
Request	A call for information from an API server.
Resource	A piece of information returned by an API. DR (pls edit this edit): Refers to a particular type or category of the information in an API, and each API resource has one or more endpoints. Users access and interact with the various aspects of a resource’s information through calls to its endpoint(s).
Response	The information or data provided from an API request.
REST	Representational State Transfer
SDK	Software Development Kit. Accompanies a REST API and is used to implement the API using a specific language, such as Java or PHP.
URI	A Uniform Resource Identifier specifies a name or locator uniquely. Some URIs begin with http:// or https://. The set of URIs includes the sets of URLs (Uniform Resource Locators) and URNs (Uniform Resource Names).
XML	Extensible Markup Language, commonly used as the message format for SOAP APIs.
YAML	Stands for “YAML Ain’t Markup Language;” YAML syntax uses colons to denote an object’s properties and hyphens to denote an array.