minim-api-description

Minim API Description Namespace

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
minim-api-description
0.9.15 years ago9 years agoMinified + gzip package size for minim-api-description in KB

Readme

Minim API Description Namespace
NPM version License
This library provides an interface to the Refract API Description namespace.
It extends upon the base types as defined in Minim.

Install

npm install minim-api-description

Usage Example

import minim from 'minim';
import apiDescription from 'minim-api-description';

const namespace = minim.namespace()
  .use(apiDescription);

// Initialize elements directly
const Category = namespace.getElementClass('category');
let category = new Category();

Element Reference

Category (ArrayElement)

A grouping element to hold other elements.

Properties

category.copy
Get an array element of all child elements with the element name copy. This property is read-only.
let copy = category.copy;
category.dataStructures
Get an array element of all child elements with the element name category and a class name dataStructures. This property is read-only.
let dataStructures = category.dataStructures;
category.resources
Get an array element of all child elements with the element name resource. This property is read-only.
let resources = category.resources;
category.resourceGroups
Get an array element of all child elements with the element name category and a class name resourceGroup. This property is read-only.
let groups = category.resourceGroups;
category.scenarios
Get an array element of all child elements with a class name scenario. This property is read-only.
let scenarios = category.scenarios;
category.transitions
Get an array element of all child elements with the element name transition. This property is read-only.
let transitions = category.transitions;
category.transitionGroups
Get an array element of all child elements with the element name category and a class name transitions. This property is read-only.
let groups = category.transitionGroups;
category.authSchemes
Get an array element of all child element with element name equal to one of the names given below. This property is read-only.
  • Basic Authentication Scheme
  • Token Authentication Scheme
  • OAuth2 Scheme

let schemes = category.authSchemes;
category.authSchemeGroups
Get an array element of all child elements with the element name category and a class name authSchemes. This property is read-only.
let groups = category.authSchemeGroups;

Copy (StringElement)

An element that contains copy text used to describe elements in the API Description namespace. The element's content contains the text:
console.log(`Description: ${copy.toValue()}`);

Properties

copy.contentType
The optional content-type of the element's content.
// Get the content-type
console.log(copy.contentType.toValue());

// Set the content-type
copy.contentType = 'text/markdown';

AuthScheme (Array Element)

This element describes an auth scheme.

Properties

scheme.copy
Get an array element of all child elements with the element name copy. This property is read-only.
let copy = scheme.copy;
scheme.transitions
Get an array element of all child elements with the element name transition. This property is read-only.
for (const transition of scheme.transitions) {
  console.log(`Transition: ${transition.title}`);
}
scheme.members
Get an array element of all child elements with the element name member. This property is read-only.
for (const member of scheme.members) {
  console.log(`Member: ${member.key}`)
}

DataStructure (Element)

This element describes a data structure.

Resource (ArrayElement)

Properties

resource.copy
Get an array element of all child elements with the element name copy. This property is read-only.
let copy = resource.copy;
resource.href
The URL template of this resource.
// Get the href
console.log(`URL: ${resource.href.toValue()}`);

// Set the href
resource.href = '/foo/{id}';
resource.hrefVariables
The description of any variables present in the resource.href URL template.
// Get the href variables
console.log(resource.hrefVariables.keys());

// Set the href variables
resource.hrefVariables = {
  id: 'foo'
}
resource.transitions
Get an array element of all child elements with the element name transition. This property is read-only.
for (const transition of resource.transitions) {
  console.log(`Transition: ${transition.title.toValue()}`);
}
resource.dataStructure
Get the first child element with the element name dataStructure. This property is read-only.
console.log(resource.dataStructure.keys());

Transition (ArrayElement)

This element represents a resource transition.

Properties

transition.copy
Get an array element of all child elements with the element name copy. This property is read-only.
let copy = transition.copy;
transition.method
Get the HTTP method of the transition, if there is one, by finding the first HTTP request and inspecting its method. This property is read-only.
let method = transition.method.toValue();
transition.relation
Defines a relationship to another resource or transition. Useful for hypermedia.
// Get the relation
console.log(`Relation: ${transition.relation.toValue()}`);

// Set the relation
transition.relation = '...';
transition.href
Overrides the resources URL template with one specific to this transition.
// Get the href
console.log(`URL: ${transition.href.toValue()}`);

// Set the href
transition.href = '/foo/{id}';
transition.computedHref
Gets either the transition's href or the first transaction's request's href if it exists, otherwise returns null. This property is read-only.
console.log(`URL: ${transition.computedHref.toValue()}`);
transition.hrefVariables
The description of any variables present in the transition.href URL template.
// Get the href variables
console.log(transition.hrefVariables.keys());

// Set the href variables
transition.hrefVariables = {
  id: 'foo'
}
transition.data
The data structure describing the body payload for this transition.
// Get the data attributes
console.log(transition.data.toRefract());

// Set the data attributes
transition.data = minim.toElement({one: 1});
transition.contentTypes
A list of content types supported by the transition.
// Get the content types
console.log(transition.contentTypes);

// Set the content types
transition.contentTypes = [
  'application/json',
  'application/yaml'
]
transition.transactions
An array element of HTTP transaction elements. This property is read-only.
// Print out each transaction's HTTP request method
for (const transaction of transition.transactions) {
  console.log(`${transaction.request.method}`);
}

HttpTransaction (ArrayElement)

This element represents an HTTP transaction.

Properties

transaction.request
The HTTP request component of this transaction. It returns an HttpRequest element if one has been defined. This property is read-only.
// Get the HTTP request
let request = transaction.request;
transaction.response
The HTTP response component of this transaction. It returns an HttpResponse element if one has been defined. This property is read-only.
// Get the HTTP response
let response = transaction.response;
transaction.authSchemes
It returns an array of elements derived from AuthScheme elements. This property is read-only.
let schemes = transaction.authSchemes;

HttpRequest (ArrayElement)

This element represents an HTTP request.

Properties

request.copy
Get an array element of all child elements with the element name copy. This property is read-only.
let copy = request.copy;
request.method
The HTTP method of this request, e.g. GET or POST.
// Get the HTTP method
console.log(`HTTP method: ${request.method.toValue()}`);

// Set the HTTP method
request.method = 'PUT';
request.href
Overrides the resources URL template with one specific to this request.
// Get the href
console.log(`URL: ${request.href.toValue()}`);

// Set the href
request.href = '/foo/{id}';
request.headers
The HTTP headers for this request. See also the request.header(name) shortcut, which will get the values for a header by name.
// Get the headers element
let headers = request.headers;

// Set the headers element
request.headers = new HttpHeaders();
request.contentType
The computed content type of this request, either from a Content-Type header or from the message content. This property is read-only.
// Get the content type
console.log(`${request.contentType}`);
request.dataStructure
The request body data structure, if it exists. This property is read-only.
let data = request.dataStructure;
request.messageBody
The request body content, if it exists. This property is read-only.
// Print out the body content as a string
console.log(`Body: ${request.messageBody}`);
request.messageBodySchema
The request body schema, if it exists. This property is read-only.
// Print out the body schema as a string
console.log(`Schema: ${request.messageBodySchema}`);

Methods

request.header(name)
Get a case-insensitive header by name. This returns a list of strings, because headers can be defined multiple times.
// Get the content type header
let type = request.header('Content-Type')[0].toValue();

HttpResponse (ArrayElement)

This element represents an HTTP response.

Properties

response.copy
Get an array element of all child elements with the element name copy. This property is read-only.
let copy = response.copy;
response.statusCode
The HTTP status code, e.g. 200 or 404.
// Get the status code
console.log(`Code: ${response.statusCode.toValue()}`);

// Set the status code
response.statusCode = 400;
response.headers
The HTTP headers for this response. See also the response.header(name) shortcut, which will get the values for a header by name.
// Get the headers element
let headers = response.headers;

// Set the headers element
response.headers = new HttpHeaders();
response.contentType
The computed content type of this response, either from a Content-Type header or from the message content. This property is read-only.
// Get the content type
console.log(`${response.contentType.toValue()}`);
response.dataStructure
The response body data structure, if it exists. This property is read-only.
let data = response.dataStructure;
response.messageBody
The response body content, if it exists. This property is read-only.
// Print out the body content as a string
console.log(`Body: ${response.messageBody}`);
response.messageBodySchema
The response body schema, if it exists. This property is read-only.
// Print out the body schema as a string
console.log(`Schema: ${response.messageBodySchema}`);

Methods

response.header(name)
Get a case-insensitive header by name. This returns a list of strings, because headers can be defined multiple times.
// Get the content type header
let type = response.header('Content-Type')[0];

Asset (Element)

This element represents an HTTP message payload or schema asset.

Properties

asset.contentType
The content type of this asset, e.g. application/json.
// Get the content type
console.log(`Type: ${asset.contentType.toValue()}`);

// Set the content type
asset.contentType = 'application/yaml';
asset.href
A link to this asset.
// Get the link
console.log(`Location: ${asset.href.toValue()}`);

// Set the link
asset.href = '/path/to/asset'

HrefVariables (ObjectElement)

This element represents a set of URI template variables.

HttpHeaders (ArrayElement)

This element represents a set of HTTP headers.

Methods

headers.include(name)
Return a filtered array element of headers with the given case-insensitive name. Each header is a member element where the key is the header name and the value is the header value.
let accept = headers.include('Accept');
headers.exclude(name)
Return a filtered array element of headers without the given case-insensitive name. Each header is a member element where the key is the header name and the value is the header value.
let filtered = headers.exclude('Content-Type');

Extension (Element)

This element represents the API Elements extensions element.

Properties

profile
Gets the extension elements profile href. This property is read-only.
let profile = extension.profile.toValue();