A specification for Javascript APIs
Version 1.1.0
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
An entity refers to an 'endpoint' in the API, e.g. a method, class, module, namespace etc.
The different entities are separated into tiers to make referencing easier. When a tier is referenced, any of the entities in that tier are allowed in place of the tier.
Field | Type | Description |
---|---|---|
spec | const 1.1.0 |
REQUIRED. The specification version the document uses. |
info | Info object | REQUIRED. Metadata about the API. |
examples | Array<string > |
Examples showing how to use this API. |
entries | Map<string , Entity Object> |
REQUIRED. An object holding the entry points available for the API. |
definitions | Map<string , Entity Object> |
Additional entities reachable through the entry points. |
{
spec: '1.1.0',
info: { /* info object */ },
entries: {
getName: { /* entity object */ }
},
definitions: {
Name: { /* entity object */ }
}
}
Field | Type | Description |
---|---|---|
name | string |
Name of the API. |
description | string |
Description of the API. |
version | string |
REQUIRED. Version of the API. |
license | string |
REQUIRED. SPDX license identifier for the API. |
{
"name": "PaymentAPI",
"description": "Pay me!",
"version": "1.3.0",
"license": "MIT"
}
Field | Type | Description |
---|---|---|
description | string |
A description of the entity. |
stability | 'experimental' | 'stable' | 'locked' |
The stability of the entity. |
availability | Availability Object | The availability of the entity. |
examples | Array<string > |
Examples showing how to use this entity. |
type | string |
The type of this entity. |
name | string |
Name of this entity. |
optional | boolean |
Optionality of this entity. Used to indicate when the entity is optional as a method parameter or an object entry. |
nullable | boolean |
Nullability of this entity. Used to indicate when the entity is nullable as a method parameter or an object entry. |
variable | boolean |
Variability of this entity. Used to indicate when the entity is repeatable as a method parameter. |
generics | Array<Entity Tier 3> | Generic types. |
defaultValue | number | boolean | string |
Default value for this entity. Used when the entity is optional. |
templates | Array<Named Object | Entity Tier 3> | The generic templates for this entity. |
{
"type": "number"
"description": "Get the current amount",
"stability": "stable",
"availability": {
"since": "1.1.0"
},
"optional": true,
"defaultValue": 13
}
Field | Type | Description |
---|---|---|
since | string |
API version from which owning entity is available. |
deprecated | boolean | Deprecated Object |
Current deprecation status of owning entity. |
{
"since": "1.0.0",
"deprecated": false
}
Field | Type | Description |
---|---|---|
since | string |
REQUIRED. API version from which owning entity is considered deprecated. |
description | string |
A short description and a recommendation on what to use instead of the deprecated entity. |
{
"since": "1.4.5",
"description": "Deprecated since 1.4.5, use something else instead :P."
}
This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:
This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:
This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:
Alias | Enum | Class | Interface
This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:
Entity Base | Literal | Object | Function | Array | Union
This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'alias' |
REQUIRED. |
items | Entity Tier 3 | REQUIRED. |
{
"kind": "alias",
"items": {
"kind": "union",
"items": [{ "type": "string" }, { "type": "number" }]
}
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'enum' |
REQUIRED. |
entries | Object<string , Literal> |
REQUIRED. An object. |
{
"kind": "enum",
"entries": {
"CODE": {
"kind": "literal",
"value": 2
}
}
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'literal' |
REQUIRED. |
value | number | boolean | string |
REQUIRED. |
{
"kind": "literal",
"value": 13
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'module' |
REQUIRED. |
entries | Object<string , Entity Tier 1 | Entity Tier 2 | Entity Tier 3> |
An object. |
definitions | Object<string , Entity Tier 1 | Entity Tier 2 | Entity Tier 3> |
An object. |
events | Object<string , Event> |
An object. |
{
"kind": "module",
"entries": {
"a": { /* entity */ },
"b": { /* entity */ }
}
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'object' |
REQUIRED. |
extends | Array<Entity Base> | References to other entities this entity extends from. |
implements | Array<Entity Base> | References to other entities this entity implements. |
entries | Object<string , Entity Tier 3> |
An object. |
definitions | Object<string , Entity Tier 3> |
An object. |
events | Object<string , Event> |
An object. |
{
"kind": "object",
"entries": {
"prop": { /* entity */ }
}
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'namespace' |
REQUIRED. |
entries | Object<string , Entity Tier 1 | Entity Tier 2 | Entity Tier 3> |
An object. |
definitions | Object<string , Entity Tier 1 | Entity Tier 2 | Entity Tier 3> |
An object. |
events | Object<string , Event> |
An object. |
{
"kind": "namespace",
"entries": {
"subspace": { /* entity */ }
}
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'function' |
REQUIRED. |
params | Array<Entity Tier 3> | REQUIRED. The parameters for this entity. |
returns | Entity Tier 3 | The return type from this entity. |
this | Entity Tier 3 | The value of this . |
async | boolean |
Indicates whether this function is asynchronous. |
yields | Array<Entity Tier 3> | The entities this function yields. |
emits | Array<Entity Base> | The events this entity emits. |
throws | Array<Entity Base> | The errors this entity throws. |
entries | Object<string , Entity Tier 3> |
An object. |
definitions | Object<string , Entity Tier 3> |
An object. |
events | Object<string , Event> |
An object. |
{
"kind": "function",
"params": [{
"name": "first"
"type": "string",
"optional": true,
"variable": true
}],
"returns": {
"type": "Promise<number>"
},
"async": true
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'class' |
REQUIRED. |
extends | Array<Entity Base> | References to other entities this entity extends from. |
implements | Array<Entity Base> | References to other entities this entity implements. |
constructor | Constructor Object | |
staticEntries | Object<string , Entity Tier 3> |
An object. |
entries | Object<string , Entity Tier 3> |
An object. |
definitions | Object<string , Entity Tier 2 | Entity Tier 3> |
An object. |
events | Object<string , Event> |
An object. |
{
"kind": "class",
"constructor": {
"params": []
},
"staticEntries": {
"fun": { /* entity */ }
}
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'function' |
REQUIRED. |
params | Array<Entity Tier 3> | The parameters for this entity. |
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'interface' |
REQUIRED. |
params | Array<Entity Tier 3> | The parameters for this entity. |
returns | Entity Tier 3 | The return type from this entity. |
this | Entity Tier 3 | The value of this . |
extends | Array<Entity Base> | References to other entities this entity extends from. |
implements | Array<Entity Base> | References to other entities this entity implements. |
entries | Object<string , Entity Tier 3> |
An object. |
definitions | Object<string , Entity Tier 2 | Entity Tier 3> |
An object. |
events | Object<string , Event> |
An object. |
{
"kind": "interface",
"entries": {
"a": { /* entity */ }
}
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'event' |
REQUIRED. |
params | Array<Entity Tier 3> | The parameters for this entity. |
returns | Entity Tier 3 | The return type from this entity. |
this | Entity Tier 3 | The value of this . |
entries | Object<string , Entity Tier 3> |
An object. |
definitions | Object<string , Entity Tier 3> |
An object. |
{
"kind": "event",
"params": []
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'array' |
REQUIRED. |
items | Array<Entity Tier 3> | Entity Tier 3 | |
definitions | Object<string , Entity Tier 3> |
An object. |
{
"kind": "array",
"items": { /* entity */ } // all values in array are of same type
}
{
"kind": "array",
"items": [ {/* entity */ }, { /* entity */ }] // tuple
}
This entity extends from Entity Base and accepts all its fields as well.
Field | Type | Description |
---|---|---|
kind | const 'union' |
REQUIRED. |
items | Array<Entity Tier 3> | |
definitions | Object<string , Entity Tier 3> |
An object. |
{
"kind": "union",
"items": [{ /* entity */ }, { /* entity */ }]
}