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

$3

You can use the library as a Maven dependency:

``xml

io.github.std-uritemplate
std-uritemplate
REPLACE-ME

`

in Gradle:

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

and use it in your project:

`java
import io.github.stduritemplate.StdUriTemplate;

...

StdUriTemplate.expand(template, substitutions);
`

$3

Install the package with pip (or any alternative):

`bash
pip install std-uritemplate
`

Use the library in your project:

`python
from stduritemplate import StdUriTemplate

...

StdUriTemplate.expand(template, substitutions)
`

$3

Install the package using npm:

`bash
npm i @std-uritemplate/std-uritemplate
`

Use the package:

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

...

StdUriTemplate.expand(template, substitutions);
`

$3

Install the package:

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

and use it:

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

...

stduritemplate.Expand(template, substitutions)
`

$3

Install the package:

`bash
dotnet add package Std.UriTemplate
`

and use it:

`csharp
Std.UriTemplate.Expand(template, substitutions);
`

$3

Install the package:

`bash
gem install stduritemplate
`

and use it:

`ruby
require 'stduritemplate'

...

StdUriTemplate.expand(template, substitutions)
`

$3

`bash
composer require stduritemplate/stduritemplate
`

and use it:

`php
use StdUriTemplate\StdUriTemplate;

...

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

$3

Install the package, adding to Package.swift:

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

and use it:

`swift
import stduritemplate

...

StdUriTemplate.expand(template, substitutions: substs)
`

$3

Install the package:

`bash
dart pub add std_uritemplate
`

for flutter:

`bash
flutter pub add std_uritemplate
`

and use it:

`dart
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):

`java
String expand(String template, Map 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.