/std-uritemplate

A complete and maintained cross-language implementation of the Uri Template specification RFC 6570 Level 4

Primary LanguageC#Apache License 2.0Apache-2.0

std-uritemplate

GitHub license Build Status GitHub Release Maven Central NPM version Go Reference PyPI Version NuGet Version Gem Version Packagist Version Pub Version PRs Welcome

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

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

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

alt_text

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.