std-uritemplate
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)
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
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';
...
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](https://imgs.xkcd.com/comics/dependency.png)
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.