Std.UriTemplate 2.0.11
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 | ✅ | ✅ | ✅ |
| Rust | ✅ | ❌ | ✅ |
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));
Rust
Add the dependency to your Cargo.toml:
[dependencies]
std-uritemplate = "REPLACE-ME"
and use it:
use stduritemplate::{expand, Value};
use std::collections::HashMap;
...
let mut substitutions = HashMap::new();
substitutions.insert("var".to_string(), Value::String("value".to_string()));
let result = expand(template, &substitutions).unwrap();
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.