std_uritemplate 2.0.3

A Dart implementation of URI Templates defined in (RFC 6570).

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>

copied to clipboard

in Gradle:

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

copied to clipboard

and use it in your project:

import io.github.stduritemplate.StdUriTemplate;

...

StdUriTemplate.expand(template, substitutions);

copied to clipboard

Python

Install the package with pip (or any alternative):

pip install std-uritemplate

copied to clipboard

Use the library in your project:

from stduritemplate import StdUriTemplate

...

StdUriTemplate.expand(template, substitutions)

copied to clipboard

Typescript/Javascript

Install the package using npm:

npm i @std-uritemplate/std-uritemplate

copied to clipboard

Use the package:

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

...

StdUriTemplate.expand(template, substitutions);

copied to clipboard

Go

Install the package:

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

copied to clipboard

and use it:

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

...

stduritemplate.Expand(template, substitutions)

copied to clipboard

C#

Install the package:

dotnet add package Std.UriTemplate

copied to clipboard

and use it:

Std.UriTemplate.Expand(template, substitutions);

copied to clipboard

Ruby

Install the package:

gem install stduritemplate

copied to clipboard

and use it:

require 'stduritemplate'

...

StdUriTemplate.expand(template, substitutions)

copied to clipboard

PHP

Install the package:

composer require stduritemplate/stduritemplate

copied to clipboard

and use it:

use StdUriTemplate\StdUriTemplate;

...

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

copied to clipboard

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")
            ]
            ...
            ),
    ]
)

copied to clipboard

and use it:

import stduritemplate

...

StdUriTemplate.expand(template, substitutions: substs)

copied to clipboard

Dart

Install the package:

dart pub add std_uritemplate

copied to clipboard

for flutter:

flutter pub add std_uritemplate

copied to clipboard

and use it:

import 'package:std_uritemplate/std_uritemplate.dart';

...

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

copied to clipboard

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)

copied to clipboard

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.