Std.UriTemplate 2.0.0

std-uritemplate

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

[!NOTE]
Low activity is this repository is expected as long as there are no outstanding bug reports the implementations are considered stable and mature.

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';

...

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 only for primitive types

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.