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

Installation

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

1 $ npm install openapi-server-url-templating

Usage

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.

1import { parse } from 'openapi-server-url-templating';
2
3const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
4parseResult.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

1import { parse } from 'openapi-server-url-templating';
2
3const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
4const parts = [];
5
6parseResult.ast.translate(parts);

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

1[
2  [
3    'server-url-template',
4    'https://{username}.gigantic-server.com:{port}/{basePath}'
5  ],
6  [ 'literals', 'https://' ],
7  [ 'server-variable', '{username}' ],
8  [ 'server-variable-name', 'username' ],
9  [ 'literals', '.gigantic-server.com:' ],
10  [ 'server-variable', '{port}' ],
11  [ 'server-variable-name', 'port' ],
12  [ 'literals', '/' ],
13  [ 'server-variable', '{basePath}' ],
14  [ 'server-variable-name', 'basePath' ]
15]

Interpreting AST as XML

1import { parse } from 'openapi-server-url-templating';
2
3const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
4const xml = parseResult.ast.toXml();

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

1<?xml version="1.0" encoding="utf-8"?>
2<root nodes="10" characters="56">
3  <!-- input string -->
4  https://{username}.gigantic-server.com:{port}/{basePath}
5  <node name="server-url-template" index="0" length="56">
6    https://{username}.gigantic-server.com:{port}/{basePath}
7    <node name="literals" index="0" length="8">
8      https://
9    </node><!-- name="literals" -->
10    <node name="server-variable" index="8" length="10">
11      {username}
12      <node name="server-variable-name" index="9" length="8">
13        username
14      </node><!-- name="server-variable-name" -->
15    </node><!-- name="server-variable" -->
16    <node name="literals" index="18" length="21">
17      .gigantic-server.com:
18    </node><!-- name="literals" -->
19    <node name="server-variable" index="39" length="6">
20      {port}
21      <node name="server-variable-name" index="40" length="4">
22        port
23      </node><!-- name="server-variable-name" -->
24    </node><!-- name="server-variable" -->
25    <node name="literals" index="45" length="1">
26      /
27    </node><!-- name="literals" -->
28    <node name="server-variable" index="46" length="10">
29      {basePath}
30      <node name="server-variable-name" index="47" length="8">
31        basePath
32      </node><!-- name="server-variable-name" -->
33    </node><!-- name="server-variable" -->
34  </node><!-- name="server-url-template" -->
35</root>

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.

1import { test } from 'openapi-server-url-templating';
2
3test('https://{username}.gigantic-server.com:{port}/{basePath}'); // => true
4test('https://gigantic-server.com/base-path'); // => true
5test('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.

1import { substitute } from 'openapi-server-url-templating';
2
3subtitute('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.

1import { substitute } from 'openapi-server-url-templating';
2
3substitute('https://{username}.gigantic-server.com', { username: '/?#' }, {
4  encoder: (serverVariable) => serverVariable, // no encoding
5}); // => "https:///?#.gigantic-server.com"

Grammar

New grammar instance can be created in following way:

1import { Grammar } from 'openapi-server-url-templating';
2
3const grammar = new Grammar();

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

1import { Grammar } from 'openapi-server-url-templating';
2
3const grammar = new Grammar();
4
5grammar.toString();
6// or
7String(grammar);

More about OpenAPI Server URL Templating

The Server URL Templating is defined by the following ABNF syntax

1; OpenAPI Server URL templating ABNF syntax
2server-url-template    = 1*( literals / server-variable ) ; variant of https://www.rfc-editor.org/rfc/rfc6570#section-2
3server-variable        = "{" server-variable-name "}"
4server-variable-name   = 1*( %x00-7A / %x7C / %x7E-10FFFF ) ; every UTF8 character except { and } (from OpenAPI)
5
6; https://www.rfc-editor.org/rfc/rfc6570#section-2.1
7; https://www.rfc-editor.org/errata/eid6937
8literals               = 1*( %x21 / %x23-24 / %x26-3B / %x3D / %x3F-5B
9                       / %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
10                       / pct-encoded)
11                            ; any Unicode character except: CTL, SP,
12                            ;  DQUOTE, "%" (aside from pct-encoded),
13                            ;  "<", ">", "\", "^", "`", "{", "|", "}"
14
15; https://www.rfc-editor.org/rfc/rfc6570#section-1.5
16DIGIT          =  %x30-39             ; 0-9
17HEXDIG         =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F" ; case-insensitive
18
19pct-encoded    =  "%" HEXDIG HEXDIG
20
21ucschar        =  %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF
22               /  %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
23               /  %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
24               /  %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
25               /  %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
26               /  %xD0000-DFFFD / %xE1000-EFFFD
27
28iprivate       =  %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.