Std.UriTemplate 0.0.54

std-uritemplate

This is intended to become a complete and maintained cross-language implementation of the Uri Template specification RFC 6570 Level 4.

Available implementations

Usage

Java

You can use the library as a Maven dependency:

<dependency>
    <groupId>io.github.std-uritemplate</groupId>
    <artifactId>std-uritemplate</artifactId>
    <version>REPLACE-ME</version>
</dependency>

in Gradle:

implementation 'io.github.std-uritemplate:std-uritemplate:REPLACE-ME'

and use it in your project:

import io.github.stduritemplate.StdUriTemplate;

...

StdUriTemplate.expand(template, substitutions);

Python

Install the package with pip (or any alternative):

pip install std-uritemplate

Use the library in your project:

from stduritemplate import StdUriTemplate

...

StdUriTemplate.expand(template, substitutions)

Typescript/Javascript

Install the package using npm:

npm i @std-uritemplate/std-uritemplate

Use the package:

const { StdUriTemplate } = require('@std-uritemplate/std-uritemplate');

...

StdUriTemplate.expand(template, substitutions);

Go

Install the package:

go get github.com/std-uritemplate/std-uritemplate/go

and use it:

import stduritemplate "github.com/std-uritemplate/std-uritemplate/go"

...

stduritemplate.Expand(template, substitutions)

C#

Install the package:

dotnet add package Std.UriTemplate

and use it:

Std.UriTemplate.Expand(template, substitutions);

Ruby

Install the package:

gem install stduritemplate

and use it:

require 'stduritemplate'

...

StdUriTemplate.expand(template, substitutions)

PHP

Install the package:

composer require stduritemplate/stduritemplate

and use it:

use StdUriTemplate\StdUriTemplate;

...

StdUriTemplate::expand($template, $substitutions);

Swift

Install the package, adding to Package.swift:

let package = Package(
    ...
    dependencies: [
        ...
        .package(
            url: "https://github.com/std-uritemplate/std-uritemplate-swift.git", 
            from: "<version>"
        )
    ],
    targets: [
        .executableTarget(
            ...
            dependencies: [
                ...
                .product(name: "stduritemplate",
                        package: "std-uritemplate-swift")
            ]
            ...
            ),
    ]
)

and use it:

import stduritemplate

...

StdUriTemplate.expand(template, substitutions: substs)

Dart

Install the package:

dart pub add std_uritemplate

for flutter:

flutter pub add std_uritemplate

and use it:

import 'package:std_uritemplate/std_uritemplate.dart';

void main() {
  final template = 'https://example.com/{var}';
  final substitutions = {'var': 'value'};

  print(StdUriTemplate.expand(template, substitutions));
}

Design decisions

We have a set of design decisions to guide:

• zero dependencies
• no usage of regexp
• no options/configurations
• only single expansion will be supported
• single method public API
• no language idiomatic API, only 1 low level primitive - we do encourage language-specific wrapper/alternative libraries
• portable implementation across languages based on widely available patterns
• target Level support is 4 (should pass all the canonical tests)
• favor maintenance and readability
• performance until they compromise readability
• one implementation per ecosystem/runtime (e.g. 1 implementation in Java and no Kotlin/Scala/Closure, 1 in TS that will serve JS as well etc.)
• substitutions will be performed for primitive types and date-time

API

The public API is composed by a single method(in Java for simplicity):

String expand(String template, Map<String, Object> substitutions)

all the rest, should not be directly accessible.

Motivation

<img alt="alt_text" src="https://imgs.xkcd.com/comics/dependency.png" />

In the Kiota project they are using Uri Templates to build URLs, and we have already spent enough life-time dealing with:

• unmaintained projects
• scarce feedback from maintainers
• long release cycles
• different nuances in different implementations
• quirks and integration issues
• frameworks and additional dependencies
• diamond transitive dependencies

We aim to do it differently, by reducing maintenance to a minimum by automating it, and sharing responsibilities to reduce the bus/truck factor:

• single repository
• multiple implementations
• fully automated testing standardized
• fully automated releases on tag
• same tradeoffs across languages
• familiar implementation across languages
• multiple maintainers in an independent organization

Uri Template is(likely) going to be included in the next OpenAPI specification and we need to rely on a (more) solid foundation to prevent our selves to spend long, tedious hours and days chasing hidden bugs, verifying compatibilities and waiting for unresponsive maintainers.