Skip to content
This repository has been archived by the owner on Nov 8, 2024. It is now read-only.

Commit

Permalink
Clarification of some terms around Transaction Examples.
Browse files Browse the repository at this point in the history
  • Loading branch information
honzajavorek committed Jan 22, 2016
1 parent b458fbd commit ab7249c
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 7 deletions.
4 changes: 2 additions & 2 deletions API Blueprint Specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -666,9 +666,9 @@ This section **may** include one nested [Attributes section][] defining the inpu
Action section **should** include at least one nested [Response section](#def-response-section) and **may** include additional nested [Request](#def-request-section) and [Response](#def-response-section) sections.
Nested Request and Response sections **may** be ordered into groups where each groups represent one transaction example. First transaction example group starts with the first nested Request or Response section. Subsequent groups start with the first nested Request section following a Response section.
Nested Request and Response sections **may** be ordered into implicit groups where each such group represents one transaction example. First transaction example group starts with the first nested Request or Response section. Subsequent groups start with the first nested Request section following a Response section.
Multiple Request and Response nested sections within one transaction example **should** have different identifiers.
Multiple nested Request and Response sections within one transaction example **should** have different identifiers.
#### Example
Expand Down
21 changes: 16 additions & 5 deletions Glossary of Terms.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ A brief list of terms as used in the [API Blueprint](http://apiblueprint.org) co

<a name="def-action"></a>
### Action
An **HTTP transaction** (a request-response transaction).
One or more [**HTTP Transactions**](#def-transaction) within a [Resource](#def-resource) with a common [HTTP Request Method](#def-method).

Actions are specified by an [HTTP request method](#def-method) within a [resource](#def-resource).
[Requests](#def-request) and [Responses](#def-response) within an Action may be ordered into implicit groups where each such group represents one [**HTTP Transaction Example**](#def-transaction-example).

<a name="def-api"></a>
### API
Expand Down Expand Up @@ -48,7 +48,7 @@ An [**HTTP Request Method**](http://en.wikipedia.org/wiki/Hypertext_Transfer_Pro

<a name="def-message"></a>
### Message
An **HTTP transaction message**.
An **HTTP ction message**.

<a name="def-message-body"></a>
### Message body
Expand Down Expand Up @@ -83,18 +83,30 @@ A [**payload**](#def-payload) containing one specific [HTTP Response](http://www
### Resource
An API [**resource**](http://www.w3.org/TR/di-gloss/#def-resource) specified by its *URI*. It can also refer to a [**set of resources**](#def-resource) matching one [**URI template**](#def-uri-template).

<a name="def-resource-group"></a>
### Resource Group
An arbitrary grouping of one or more [**Resource Sets**](#def-resource-set).

<a name="def-resource-model"></a>
### Resource Model
One [**manifestation of a resource**](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) in the form of a [payload](#def-payload). A resource model is an example representation of its resource. Can be referenced later in the place of a [payload](#def-payload).

<a name="def-resource-set"></a>
### Resource Set
A set of API [**resources**](http://www.w3.org/TR/di-gloss/#def-resource) its *URI* matches one specific [**URI template**](#def-uri-template).
A set of API [**resources**](http://www.w3.org/TR/di-gloss/#def-resource) with *URI*, which matches one specific [**URI template**](#def-uri-template).

<a name="def-trait"></a>
### Trait
A quality or characteristic of an API Blueprint SECTION.

<a name="def-transaction"></a>
### Transaction
[HTTP Request](#def-request) with a corresponding [HTTP Response](#def-response).

<a name="def-transaction-example"></a>
### Transaction Example
An implicit group of one or more [Requests](#def-request) and one or more corresponding [Responses](#def-response). If expanded into Request-Response pairs, it represents one or more [**HTTP Transactions**](#def-transaction).

<a name="def-schema"></a>
### Schema
A **validation schema** in a form of an [**asset**](#def-asset) used to validate (or describe) a [**message-body**](#def-message-body).
Expand All @@ -113,4 +125,3 @@ A compact sequence of characters for describing a range of **Uniform Resource Id


[MSON]: https://github.com/apiaryio/mson

0 comments on commit ab7249c

Please sign in to comment.