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

Language	Complete	Reviewed	Published
Java	✅	✅	✅
Python	✅	❌	✅
Typescript	✅	✅	✅
Go	✅	✅	✅
C#	✅	✅	✅
Ruby	✅	❌	✅
PHP	✅	✅	✅
Swift	✅	❌	✅
Dart	✅	✅	✅

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/v2

and use it:

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

...

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

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.

Package profile

std-uritemplate

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description