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