@btilford/uri-template/docs/_includes/usage.html

Javascript RFC 6570 URI template

<section class="suite">
<h1>1. Example - UriTemplate</h1>
<dl>
<dd>
<section class="suite">
<h1>Basics</h1>
<dl>
<dt>The simplest expansion</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('https://xyz/{name}')
  .expand({
    name: 'abc'
  })
  .format();
expect(val).to.equal('https://xyz/abc');
{% endhighlight  %}
</dd>
<dt>A bit more</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('https://app{.host*}{/version,path*}{?a,b,c*}{#some-id}')
  .expand({
    host: ['acme', 'com'],
    path: ['some', 'thing'],
    version: 'v2',
    a: 'A',
    b: 'B',
    c: 'the letter c',
    'some-id': 'thing 1'
  })
  .format();
expect(val).to.equal('https://app.acme.com/v2/some/thing?a=A?b=B?c=the%20letter%20c#thing%201');
{% endhighlight  %}
</dd>
</dl>
</section>
<section class="suite">
<h1>Chained Expansion</h1>
<dl>
<dt>Allows leaving the template in tact after adding a hostname</dt>
<dd>
{% highlight javascript %}
uriTemplate = uriTemplate.expand({ env: 'localhost' });
const val = uriTemplate.format();
expect(val).to.equal('https://app.localhost/path/{/id}');
{% endhighlight  %}
</dd>
<dt>And afterwards adding the rest of the params.</dt>
<dd>
{% highlight javascript %}
const val = uriTemplate.expand({ id: 123 })
  .format();
expect(val).to.equal('https://app.localhost/path/123');
{% endhighlight  %}
</dd>
<dt>You can drop unexpanded parameters.</dt>
<dd>
{% highlight javascript %}
const val = uriTemplate.format(false);
expect(val).to.equal('https://app.localhost/path/');
{% endhighlight  %}
</dd>
</dl>
</section>
<section class="suite">
<h1>Handling variable types</h1>
<dl>
<dt>Label "{.xyz}" variables</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('file{.extension}')
  .expand({ extension: 'js' })
  .format();
expect(val).to.equal('file.js');
{% endhighlight  %}
</dd>
<dt>Fragment "{#id}" variables</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('/path{#id}')
  .expand({ id: 'section 1' })
  .format();
expect(val).to.equal('/path#section%201');
{% endhighlight  %}
</dd>
<dt>Path segment "{/id}" variables</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('/path{/id}')
  .expand({ id: '123' })
  .format();
expect(val).to.equal('/path/123');
{% endhighlight  %}
</dd>
<dt>Path style param "{;id}" variables</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('/path{;id}')
  .expand({ id: '123' })
  .format();
expect(val).to.equal('/path;id=123');
{% endhighlight  %}
</dd>
<dt>Query "{?id}" variables</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('/path{?id}')
  .expand({ id: '123' })
  .format();
expect(val).to.equal('/path?id=123');
{% endhighlight  %}
</dd>
<dt>Query continuation "{&amp;offset}" variables</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('/path?limit=100{&amp;offset}')
  .expand({ offset: '300' })
  .format();
expect(val).to.equal('/path?limit=100&amp;offset=300');
{% endhighlight  %}
</dd>
<dt>Reserved string "{+redirectUri}" variables</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('https://nowhere.test/login?redirect={+redirectUri}')
  .expand({ redirectUri: 'https://github.com' })
  .format();
expect(val).to.equal('https://nowhere.test/login?redirect=https%3A%2F%2Fgithub.com');
{% endhighlight  %}
</dd>
</dl>
</section>
<section class="suite">
<h1>Variable lists</h1>
<dl>
<dt>Any type can have a list of variable slots.</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('https://api{.env,host}{/version,path}')
  .expand({
    env: 'dev',
    host: 'xyz.com',
    version: 'v2',
    path: 'resource/xyz'
  }).format();
expect(val).to.equal('https://api.dev.xyz.com/v2/resource/xyz');
{% endhighlight  %}
</dd>
</dl>
</section>
<section class="suite">
<h1>Value lists</h1>
<dl>
<dt>Without explode "*".</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('{/paths}')
  .expand({
    paths: ['bin', '/etc']
  }).format();
expect(val).to.equal('/bin,/etc');
{% endhighlight  %}
</dd>
<dt>With explode "*".</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('{/paths*}')
  .expand({
    paths: ['/usr/bin', 'bash']
  }).format();
expect(val).to.equal('/usr/bin/bash');
{% endhighlight  %}
</dd>
</dl>
</section>
<section class="suite">
<h1>Max Length</h1>
<dl>
<dt>You can provide max length "{?code:1}" (default is 10,000)</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('{?code:1}')
  .expand({ code: 'four' })
  .format();
expect(val).to.equal('?code=f');
{% endhighlight  %}
</dd>
<dt>Max Length needs to be before any explode</dt>
<dd>
{% highlight javascript %}
const good = UriTemplate.parse('{?code:1*}')
  .expand({ code: ['four', 'x'] })
  .format();
expect(good).to.equal('?code=f&amp;code=x');
const bad = UriTemplate.parse('{?code*:1}')
  .expand({ code: ['four', 'x'] })
  .format();
expect(bad).to.equal('{?code*:1}');
{% endhighlight  %}
</dd>
</dl>
</section>
<section class="suite">
<h1>Special values</h1>
<dl>
<dt>Empty vars</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('http://some/thing{?abc}')
  .expand({ abc: '' })
  .format();
expect(val).to.equal('http://some/thing?abc');
{% endhighlight  %}
</dd>
<dt>Undefined or null vars</dt>
<dd>
{% highlight javascript %}
const val = UriTemplate.parse('http://some/thing{?abc}')
  .expand({ abc: null })
  .format();
expect(val).to.equal('http://some/thing');
{% endhighlight  %}
</dd>
</dl>
</section>
</dd>
</dl>
</section>
<section class="suite">
<h1>2. Example - UriTemplateBuilder Spec</h1>
<dl>
<dd>
<section class="suite">
<h1>Basics</h1>
<dl>
<dt>The simplest thing.</dt>
<dd>
{% highlight javascript %}
const val = UriTemplateBuilder.from('http://localhost')
  .text(':')
  .simple('port')
  .format();
expect(val).to.equal('http://localhost:{port}');
{% endhighlight  %}
</dd>
<dt>This really just appends stuff.</dt>
<dd>
{% highlight javascript %}
const val = UriTemplateBuilder.from('http://localhost')
  .label('tld')
  .simple('port')
  .text('/v1')
  .path('some', 'thing')
  .query('username', 'id')
  .format();
expect(val).to.equal('http://localhost{.tld}{port}/v1{/some,thing}{?username,id}');
{% endhighlight  %}
</dd>
</dl>
</section>
</dd>
</dl>
</section>