diff --git a/docs/implementors-guide.md b/docs/implementors-guide.md new file mode 100644 index 0000000..681b146 --- /dev/null +++ b/docs/implementors-guide.md @@ -0,0 +1,21 @@ +# Implementor's Guide + +## Purpose of the type and the provider fields in the application projection + +Service Binding specification mandates `type` field and recommends `provider` field in the binding Secret resource. The provider field is recommended to support scenarios where there could be different providers for the same Provisioned Service type. For example, if the type is `mysql`, the provider value could be `mariadb`, `oracle`, `bitnami`, `aws-rds`, etc. When the application is reading the binding values, if necessary, the application could consider `type` and `provider` as a composite key to avoid ambiguity. It will be helpful if an application needs to choose a particular provider based on the deployment environment. + +The language binding API can create two separate functions to retrieve bindings (with provider and without provider). For example, in Go: + +``` +GetBinding(_type string) (map[string]string, error) +GetBindingWithProvider(_type, provider string) (map[string]string, error) +``` + +Languages with parametric polymorphism can use a method with different parameters to retrieve bindings (with provider and without provider). For example, in Java: + +``` +public List filterBindings(@Nullable String type) +public List filterBindings(@Nullable String type, @Nullable String provider) +``` + +(Example taken from [Spring Cloud Bindings](https://github.com/spring-cloud/spring-cloud-bindings))