Permalink
8cb625f May 18, 2016
@zdne @mikaa123 @kylef @jean @clekstro
131 lines (97 sloc) 4.65 KB

API Blueprint Glossary of Terms

A brief list of terms as used in the API Blueprint context.

Glossary

Action

An HTTP transaction (a request-response transaction).

Actions are specified by an HTTP request method within a resource.

API

An HTTP Application programming interface. Might refer to an API description. See API Blueprint.

API Blueprint

The API Blueprint language. A format used to describe API in an API blueprint file.

Asset

Atomic data. Most often representing one resource representation in the form of message-body or its validation schema.

Attribute

Based on the context, attribute (property) of a message-body data structure, or attribute of a resource, or an input attribute of a transition – Action.

Blueprint

An API description. A blueprint file (or a set of files) that describes an API using the API Blueprint language.

Data Structure

A particular data organization, or a description of it. In API Blueprint, data structures and their Attributes are described using the Markdown Syntax for Object Notation – MSON.

Entity

Entity being transferred in a payload.

Header

A message-header.

Method

An HTTP Request Method.

Message

An HTTP transaction message.

Message body

An asset representing HTTP transaction message body.

Message header

An asset representing HTTP transaction message header.

Parameter

An URI template variable.

Payload

An HTTP transaction message including its discussion and any additional assets such as entity-body validation schema.

A payload may have an identifier – a string for a request payload or an HTTP status code for a response payload.

Property

An entity field (attribute).

Request

A payload containing one specific HTTP Request.

Response

A payload containing one specific HTTP Response.

Resource

An API resource specified by its URI. It can also refer to a set of resources matching one URI template.

Resource Model

One manifestation of a resource in the form of a payload. A resource model is an example representation of its resource. Can be referenced later in the place of a payload.

Resource Set

A set of API resources. Its URI matches one specific URI template.

Trait

A quality or characteristic of an API Blueprint SECTION.

Schema

A validation schema in a form of an asset used to validate (or describe) a message-body.

URI template

A compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion, see RFC 6570.

Additional resources