feat: Create OpenFeature API module with ServiceLoader pattern

- Implement interface segregation (Core, Hooks, Context, Advanced)
- Add ServiceLoader singleton with priority-based provider selection
- Create no-op fallback implementation for API-only consumers
- Move core interfaces and data types from SDK to API package
- Support multiple implementations with clean API contracts
- Enable backward compatibility through abstraction layer

Key components:
- OpenFeatureAPI: Main abstract class combining all interfaces
- OpenFeatureAPIProvider: ServiceLoader interface for implementations
- NoOpOpenFeatureAPI/NoOpClient: Safe fallback implementations
- Core interfaces: Client, FeatureProvider, Hook, Metadata
- Data types: Value, Structure, EvaluationContext, exceptions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: aepfli

openfeature-api/pom.xml

@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>dev.openfeature</groupId>
+        <artifactId>openfeature-java</artifactId>
+        <version>2.0.0</version>
+    </parent>
+
+    <artifactId>openfeature-api</artifactId>
+
+    <name>OpenFeature Java API</name>
+    <description>OpenFeature Java API - Core contracts and interfaces for feature flag evaluation</description>
+
+    <properties>
+        <module-name>dev.openfeature.api</module-name>
+    </properties>
+
+    <dependencies>
+        <!-- Minimal dependencies for API -->
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>2.0.17</version>
+        </dependency>
+
+        <!-- Lombok for clean code generation -->
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <version>1.18.38</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <!-- Spotbugs for annotations -->
+        <dependency>
+            <groupId>com.github.spotbugs</groupId>
+            <artifactId>spotbugs</artifactId>
+            <version>4.8.6</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.4.2</version>
+                <configuration>
+                    <archive>
+                        <manifestEntries>
+                            <Automatic-Module-Name>${module-name}</Automatic-Module-Name>
+                        </manifestEntries>
+                    </archive>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

openfeature-api/src/main/java/dev/openfeature/api/AbstractStructure.java

@@ -0,0 +1,51 @@
+package dev.openfeature.api;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import lombok.EqualsAndHashCode;
+
+@SuppressWarnings({"PMD.BeanMembersShouldSerialize", "checkstyle:MissingJavadocType"})
+@EqualsAndHashCode
+abstract class AbstractStructure implements Structure {
+
+    protected final Map<String, Value> attributes;
+
+    @Override
+    public boolean isEmpty() {
+        return attributes == null || attributes.isEmpty();
+    }
+
+    AbstractStructure() {
+        this.attributes = new HashMap<>();
+    }
+
+    AbstractStructure(Map<String, Value> attributes) {
+        this.attributes = attributes;
+    }
+
+    /**
+     * Returns an unmodifiable representation of the internal attribute map.
+     *
+     * @return immutable map
+     */
+    public Map<String, Value> asUnmodifiableMap() {
+        return Collections.unmodifiableMap(attributes);
+    }
+
+    /**
+     * Get all values as their underlying primitives types.
+     *
+     * @return all attributes on the structure into a Map
+     */
+    @Override
+    public Map<String, Object> asObjectMap() {
+        return attributes.entrySet().stream()
+                // custom collector, workaround for Collectors.toMap in JDK8
+                // https://bugs.openjdk.org/browse/JDK-8148463
+                .collect(
+                        HashMap::new,
+                        (accumulated, entry) -> accumulated.put(entry.getKey(), convertValue(entry.getValue())),
+                        HashMap::putAll);
+    }
+}

openfeature-api/src/main/java/dev/openfeature/api/BaseEvaluation.java

@@ -0,0 +1,44 @@
+package dev.openfeature.api;
+
+/**
+ * This is a common interface between the evaluation results that providers return and what is given to the end users.
+ *
+ * @param <T> The type of flag being evaluated.
+ */
+public interface BaseEvaluation<T> {
+    /**
+     * Returns the resolved value of the evaluation.
+     *
+     * @return {T} the resolve value
+     */
+    T getValue();
+
+    /**
+     * Returns an identifier for this value, if applicable.
+     *
+     * @return {String} value identifier
+     */
+    String getVariant();
+
+    /**
+     * Describes how we came to the value that we're returning.
+     *
+     * @return {Reason}
+     */
+    String getReason();
+
+    /**
+     * The error code, if applicable. Should only be set when the Reason is ERROR.
+     *
+     * @return {ErrorCode}
+     */
+    ErrorCode getErrorCode();
+
+    /**
+     * The error message (usually from exception.getMessage()), if applicable.
+     * Should only be set when the Reason is ERROR.
+     *
+     * @return {String}
+     */
+    String getErrorMessage();
+}

openfeature-api/src/main/java/dev/openfeature/api/BooleanHook.java

@@ -0,0 +1,15 @@
+package dev.openfeature.api;
+
+/**
+ * An extension point which can run around flag resolution. They are intended to be used as a way to add custom logic
+ * to the lifecycle of flag evaluation.
+ *
+ * @see Hook
+ */
+public interface BooleanHook extends Hook<Boolean> {
+
+    @Override
+    default boolean supportsFlagValueType(FlagValueType flagValueType) {
+        return FlagValueType.BOOLEAN == flagValueType;
+    }
+}

openfeature-api/src/main/java/dev/openfeature/api/Client.java

@@ -0,0 +1,46 @@
+package dev.openfeature.api;
+
+import java.util.List;
+
+/**
+ * Interface used to resolve flags of varying types.
+ */
+public interface Client extends Features, Tracking, EventBus<Client> {
+    ClientMetadata getMetadata();
+
+    /**
+     * Return an optional client-level evaluation context.
+     *
+     * @return {@link EvaluationContext}
+     */
+    EvaluationContext getEvaluationContext();
+
+    /**
+     * Set the client-level evaluation context.
+     *
+     * @param ctx Client level context.
+     */
+    Client setEvaluationContext(EvaluationContext ctx);
+
+    /**
+     * Adds hooks for evaluation.
+     * Hooks are run in the order they're added in the before stage. They are run in reverse order for all other stages.
+     *
+     * @param hooks The hook to add.
+     */
+    Client addHooks(Hook... hooks);
+
+    /**
+     * Fetch the hooks associated to this client.
+     *
+     * @return A list of {@link Hook}s.
+     */
+    List<Hook> getHooks();
+
+    /**
+     * Returns the current state of the associated provider.
+     *
+     * @return the provider state
+     */
+    ProviderState getProviderState();
+}

openfeature-api/src/main/java/dev/openfeature/api/ClientMetadata.java

@@ -0,0 +1,14 @@
+package dev.openfeature.api;
+
+/**
+ * Metadata specific to an OpenFeature {@code Client}.
+ */
+public interface ClientMetadata {
+    String getDomain();
+
+    @Deprecated
+    // this is here for compatibility with getName() exposed from {@link Metadata}
+    default String getName() {
+        return getDomain();
+    }
+}

openfeature-api/src/main/java/dev/openfeature/api/DoubleHook.java

@@ -0,0 +1,15 @@
+package dev.openfeature.api;
+
+/**
+ * An extension point which can run around flag resolution. They are intended to be used as a way to add custom logic
+ * to the lifecycle of flag evaluation.
+ *
+ * @see Hook
+ */
+public interface DoubleHook extends Hook<Double> {
+
+    @Override
+    default boolean supportsFlagValueType(FlagValueType flagValueType) {
+        return FlagValueType.DOUBLE == flagValueType;
+    }
+}

openfeature-api/src/main/java/dev/openfeature/api/ErrorCode.java

@@ -0,0 +1,13 @@
+package dev.openfeature.api;
+
+@SuppressWarnings("checkstyle:MissingJavadocType")
+public enum ErrorCode {
+    PROVIDER_NOT_READY,
+    FLAG_NOT_FOUND,
+    PARSE_ERROR,
+    TYPE_MISMATCH,
+    TARGETING_KEY_MISSING,
+    INVALID_CONTEXT,
+    GENERAL,
+    PROVIDER_FATAL
+}

openfeature-api/src/main/java/dev/openfeature/api/EvaluationContext.java

@@ -0,0 +1,63 @@
+package dev.openfeature.api;
+
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.function.Function;
+
+/**
+ * The EvaluationContext is a container for arbitrary contextual data
+ * that can be used as a basis for dynamic evaluation.
+ */
+@SuppressWarnings("PMD.BeanMembersShouldSerialize")
+public interface EvaluationContext extends Structure {
+
+    String TARGETING_KEY = "targetingKey";
+
+    String getTargetingKey();
+
+    /**
+     * Merges this EvaluationContext object with the second overriding the this in
+     * case of conflict.
+     *
+     * @param overridingContext overriding context
+     * @return resulting merged context
+     */
+    EvaluationContext merge(EvaluationContext overridingContext);
+
+    /**
+     * Recursively merges the overriding map into the base Value map.
+     * The base map is mutated, the overriding map is not.
+     * Null maps will cause no-op.
+     *
+     * @param newStructure function to create the right structure(s) for Values
+     * @param base         base map to merge
+     * @param overriding   overriding map to merge
+     */
+    static void mergeMaps(
+            Function<Map<String, Value>, Structure> newStructure,
+            Map<String, Value> base,
+            Map<String, Value> overriding) {
+
+        if (base == null) {
+            return;
+        }
+        if (overriding == null || overriding.isEmpty()) {
+            return;
+        }
+
+        for (Entry<String, Value> overridingEntry : overriding.entrySet()) {
+            String key = overridingEntry.getKey();
+            if (overridingEntry.getValue().isStructure()
+                    && base.containsKey(key)
+                    && base.get(key).isStructure()) {
+                Structure mergedValue = base.get(key).asStructure();
+                Structure overridingValue = overridingEntry.getValue().asStructure();
+                Map<String, Value> newMap = mergedValue.asMap();
+                mergeMaps(newStructure, newMap, overridingValue.asUnmodifiableMap());
+                base.put(key, new Value(newStructure.apply(newMap)));
+            } else {
+                base.put(key, overridingEntry.getValue());
+            }
+        }
+    }
+}