openapi-server-url-templating


Server URL Templating supports Server Variables. Variable substitutions will be made when a variable is named in {brackets}.
This mechanism is used by Server Object
of OpenAPI specification.

openapi-server-url-templating is a parser, validator and substitution mechanism for OpenAPI Server URL Templating,
which played a foundational role in defining the official ANBF grammar for Server URL Templating.

It supports Server Object URL Templating defined in following OpenAPI specification versions:

- OpenAPI 3.0.0
- OpenAPI 3.0.1
- OpenAPI 3.0.2
- OpenAPI 3.0.3
- OpenAPI 3.0.4
- OpenAPI 3.1.0
- OpenAPI 3.1.1

Get professionally supported openapi-server-url-templating with Tidelift Subscription.

Table of Contents

- Getting started
- Installation
- Usage
- Parsing
- Validation
- Substitution
- Grammar
- More about OpenAPI Server URL Templating
- License

Getting started

$3

You can install openapi-server-url-templating using npm:

``sh
$ npm install openapi-server-url-templating
`

$3

openapi-server-url-templating currently supports parsing, validation and substitution.
Both parser and validator are based on a superset of ABNF (SABNF)
and use apg-lite parser generator.

#### Parsing

Parsing a Server URL Templating is as simple as importing the parse function
and calling it.

`js
import { parse } from 'openapi-server-url-templating';

const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
parseResult.result.success; // => true
`

parseResult variable has the following shape:

`
{
result: {
success: true,
state: 101,
stateName: 'MATCH',
length: 56,
matched: 56,
maxMatched: 56,
maxTreeDepth: 12,
nodeHits: 758
},
ast: fnast {
callbacks: [
'server-url-template': [Function: serverUrlTemplate],
'server-variable': [Function: serverVariable],
'server-variable-name': [Function: serverVariableName],
literals: [Function: literals]
],
init: [Function (anonymous)],
ruleDefined: [Function (anonymous)],
udtDefined: [Function (anonymous)],
down: [Function (anonymous)],
up: [Function (anonymous)],
translate: [Function (anonymous)],
setLength: [Function (anonymous)],
getLength: [Function (anonymous)],
toXml: [Function (anonymous)]
}
}
`

###### Interpreting AST as list of entries

`js
import { parse } from 'openapi-server-url-templating';

const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
const parts = [];

parseResult.ast.translate(parts);
`

After running the above code, parts variable has the following shape:

`js
[
[
'server-url-template',
'https://{username}.gigantic-server.com:{port}/{basePath}'
],
[ 'literals', 'https://' ],
[ 'server-variable', '{username}' ],
[ 'server-variable-name', 'username' ],
[ 'literals', '.gigantic-server.com:' ],
[ 'server-variable', '{port}' ],
[ 'server-variable-name', 'port' ],
[ 'literals', '/' ],
[ 'server-variable', '{basePath}' ],
[ 'server-variable-name', 'basePath' ]
]
`

###### Interpreting AST as XML

`js
import { parse } from 'openapi-server-url-templating';

const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
const xml = parseResult.ast.toXml();
`

After running the above code, xml variable has the following content:

`xml



https://{username}.gigantic-server.com:{port}/{basePath}

https://{username}.gigantic-server.com:{port}/{basePath}

https://


{username}

username



.gigantic-server.com:


{port}

port



/


{basePath}

basePath




`

> NOTE: AST can also be traversed in classical way using depth first traversal. For more information about this option please refer to apg-js and apg-js-examples.

#### Validation

Validating a Server URL Templating is as simple as importing the test function and calling it.


`js
import { test } from 'openapi-server-url-templating';

test('https://{username}.gigantic-server.com:{port}/{basePath}'); // => true
test('https://gigantic-server.com/base-path'); // => true
test('https://gigantic-server.com/base-path', { strict: true }); // => false (doesn't contain any server-variable)
`

#### Substitution

Performing Server URL template substitution is as simple as importing the substitute function and calling it.

`js
import { substitute } from 'openapi-server-url-templating';

subtitute('https://{username}.gigantic-server.com', { username: 'char0n' }); // => "https://char0n.gigantic-server.com"
`

Substituted Server URL Templating is automatically encoded using encodeURIComponent function.
It is possible to provide a custom encoder.

`js
import { substitute } from 'openapi-server-url-templating';

substitute('https://{username}.gigantic-server.com', { username: '/?#' }, {
encoder: (serverVariable) => serverVariable, // no encoding
}); // => "https:///?#.gigantic-server.com"
`

#### Grammar

New grammar instance can be created in following way:

`js
import { Grammar } from 'openapi-server-url-templating';

const grammar = new Grammar();
`

To obtain original ABNF (SABNF) grammar as a string:

`js
import { Grammar } from 'openapi-server-url-templating';

const grammar = new Grammar();

grammar.toString();
// or
String(grammar);
`

More about OpenAPI Server URL Templating

The Server URL Templating is defined by the following ABNF syntax

`abnf
; OpenAPI Server URL templating ABNF syntax
server-url-template = 1*( literals / server-variable ) ; variant of https://www.rfc-editor.org/rfc/rfc6570#section-2
server-variable = "{" server-variable-name "}"
server-variable-name = 1*( %x00-7A / %x7C / %x7E-10FFFF ) ; every UTF8 character except { and } (from OpenAPI)

; https://www.rfc-editor.org/rfc/rfc6570#section-2.1
; https://www.rfc-editor.org/errata/eid6937
literals = 1*( %x21 / %x23-24 / %x26-3B / %x3D / %x3F-5B
/ %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
/ pct-encoded)
; any Unicode character except: CTL, SP,
; DQUOTE, "%" (aside from pct-encoded),
; "<", ">", "\", "^", "", "{", "|", "}"

; https://www.rfc-editor.org/rfc/rfc6570#section-1.5
DIGIT = %x30-39 ; 0-9
HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" ; case-insensitive

pct-encoded = "%" HEXDIG HEXDIG

ucschar = %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF
/ %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
/ %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
/ %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
/ %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
/ %xD0000-DFFFD / %xE1000-EFFFD

iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD
``

License

openapi-server-url-templating is licensed under Apache 2.0 license.
openapi-server-url-templating` comes with an explicit NOTICE file
containing additional legal notices and information.