The Architectural Crossroads: Platform SDK vs. Turnkey Proxy#

These two options represent two fundamentally different approaches to software distribution and integration architecture. This is a core strategic fork in API and middleware design:

1. Option 1: The Programmatic API / SDK Approach

   • Recognized Technical Terms: Software Development Kit (SDK), Embedded Library, Programmatic API Framework, or In-Process Integration.

   • What it is essentially doing: We provide the building blocks (classes, interfaces, and algorithms), but the consumer owns the application lifecycle. The consumer writes custom code, imports our library as a dependency into their build system (like Maven or Gradle), and instantiates our classes inside their process.

   • Control Flow: In-process coupling. Our code runs inside the consumer’s JVM, sharing memory space, classloaders, and thread pools.

   • Examples:

     yahoo

     /

     fili
     Waiting for api.github.com...
     00K

     0K

     0K

     Waiting...
     yahoo

     /

     elide
     Waiting for api.github.com...
     00K

     0K

     0K

     Waiting...

2. Option 2: The Configurable Proxy / Gateway Approach

   • Recognized Technical Terms: Database Proxy, Protocol Gateway, Out-of-the-Box Middleware, or Configuration-Driven Microservice (often falling under the broader umbrella of Sidecars or Edge Routers).
   • What it is essentially doing: We ship a complete, standalone server application. The consumer treats our service as a black-box infrastructure component. They deploy it via a container or binary, pass parameters via environment variables or configuration files (like YAML), and have their business applications talk to our proxy over standard network protocols (e.g., HTTP/REST, gRPC). Our service then translates and forwards those requests to the underlying graph database.
   • Control Flow: Out-of-process decoupling. Our service runs as an independent network daemon, separated from the client application by a socket boundary.

The Business Strategy: Platform vs. Solution#

The architectural branching above maps perfectly to the platform versus solution dichotomy. these two approaches capture value and demand engagement from the user with different strategies

Option 1 (The SDK) is a platform and provides the raw programmatic primitives: the interfaces, algorithms, and data structures. It offers maximum degrees of freedom, acting as a foundation for developers to build highly customized architectures. If we apply the WHY-HOW-WHAT framework, a platform gives developers the “HOW” (the tools) but forces them to engineer the “WHAT” (the final running service) themselves. It is highly flexible but demands significant upfront effort, compilation, and maintenance.

Option 2 (The Gateway) is a solution; It is a turnkey product designed to solve a specific, immediate problem such as getting a business application connected to a certain kind of database with zero friction. It encapsulates all the internal complexity behind strict a priori network contracts, completely isolating the consumer from the underlying implementation. It delivers the final “WHAT” out-of-the-box, drastically reducing Time-to-Market and Total Cost of Ownership for the consumer.

Strategically, pure platforms often face a “cold start” adoption problem because they require the consumer to do the heavy lifting of integration. Solutions drive rapid adoption because they lower the barrier to entry to a simple configuration file and a container deployment.

Offering the solution (the proxy) often acts as the most effective entry point into an ecosystem. It solves the immediate pain point quickly, while our underlying platform (the internal library architecture) remains cleanly separated and ready to be exposed later for power users who demand absolute control.

Spec Source Code of JSR 370#

JSR 370 is the specification for JAX-RS 2.1 (Java API for RESTful Web Services). Because Java EE was transitioned to the Eclipse Foundation and rebranded as Jakarta EE, the specification’s source code has moved a few times over the years.

TIP

JAX-RS is the overarching name of the technology, while JSR 370 was simply the specific tracking number for version 2.1 of that technology.

The name progression went like this:

1. JAX-RS 1.0 / 2.0 (JSR 311/JSR 339)
2. JAX-RS 2.1 (JSR 370)
3. Jakarta RESTful Web Services (The modern name, following the migration to the Eclipse Foundation)

Depending on whether we want the modern repository or the historical archive, here is where we can find the specification’s source code.

Jersey: The Reference Implementation#

When Oracle/Sun designed a specification like JSR 370, they were required to build a concrete, working example to prove the specification worked. Jersey was built by Sun/Oracle as that official Reference Implementation. Because it was designed in the era of application servers, Jersey is highly dynamic. It scans an application at runtime using heavy Java reflection to find @Path and @GET annotations.

Quarkus: The Modern, Build-Time Implementation

While Jersey has been updated to support modern versions, its fundamental architecture was conceived in a time before cloud-native containers and instant startups were the primary goal.

Quarkus, on the other hand, is a modern framework built from scratch by Red Hat for the cloud and Kubernetes era. Quarkus developers looked at the JAX-RS (Jakarta REST) programming model, loved the annotations, but hated the slow runtime reflection used by older tools like Jersey. Instead of doing everything at runtime, Quarkus shifts all that heavy annotation scanning to compile-time. When we build a Quarkus app, it reads application’s JAX-RS annotations and generates optimized, direct bytecode.

Quarkus doesn’t actually use Jersey under the hood. It uses RESTEasy Reactive, which is an entirely separate, highly optimized implementation of the exact same JAX-RS specification.

Although faced with fierce competition from modern cloud-native frameworks, Jersey is not outdated, but it occupies a very specific professional niche:

1. Light, Standalone Web Servers

   If our goal is to build an exceptionally lean, high-throughput microservice without the massive footprint of a comprehensive framework, coupling Jersey with an embedded servlet container like Jetty or Grizzly is a top-tier architectural choice. It allows us to build a standard-compliant, lightning-fast REST API with absolute control over our dependencies.

2. Standard-Compliant Architectures

   For teams enforcing a strict separation between a specification API and the underlying framework engine, Jersey remains the premium reference implementation. We can swap Jersey for another Jakarta REST implementation (like RESTEasy) later down the road with minimal Friction.

TIP

If you are running a service built on Jersey 1.x or 2.x using old javax.* packages, that specific stack is legacy.

However, running a modern Jersey 3.x or 4.x application on a light, containerized engine is completely modern. It isn’t outdated; it is simply a deliberate, minimalist architectural choice favored by developers who prioritize explicit control and standards compliance over comprehensive framework ecosystems like Spring.

Spring Does Not Implement JAX-RS#

Spring has its own native specification and ecosystem for building REST APIs called Spring MVC. It operates as a fully functional, alternative way to handle REST endpoints without adhering to the JAX-RS standard

While both achieve the same goal, they differ in design and annotation:

• Spring MVC: Uses annotations like @RestController and @RequestMapping. It is tightly bound to the broader Spring ecosystem (e.g., Spring Security, Spring Data).
• JAX-RS: Uses annotations like @Path and @GET. It is an official Java EE (now Jakarta EE) specification with multiple independent implementations like Jersey or Apache CXF.

The underlying configuration mechanisms highlight how differently they treat the HTTP protocol:

• JAX-RS relies on composition. We use @Path to define routing, and then combine it with explicit verb annotations like @GET and explicit mime-type filters like @Produces.

  1
  // JAX-RS (JSR 370 / Jakarta REST)
  2
  @Path("/books")
  3
  public class BookResource {
  4
      @GET
  5
      @Path("/{id}")
  6
      @Produces(MediaType.APPLICATION_JSON)
  7
      public Book getBook(@PathParam("id") Long id) { ... }
  8
  }
  

• Spring prioritizes convenience and convention over strict configuration. It wraps routing and verbs together into single annotations like @GetMapping. It also infers context implicitly—for example, if a method returns a POJO and the request header asks for JSON, Spring automatically leverages Jackson to serialize it without requiring an explicit @Produces declaration on every method.

  1
  // Spring Web MVC
  2
  @RestController
  3
  @RequestMapping("/books")
  4
  public class BookController {
  5
      @GetMapping("/{id}")
  6
      public Book getBook(@PathVariable Long id) { ... }
  7
  }
  

Jakarta REST#

The name “JAX-RS”, though, is increasingly viewed as an older term. Architecturally, the specification is highly vibrant and under active, modern development. However, the ecosystem has gone through a massive rebranding and structural evolution that changes how it is perceived today. It has been renamed to Jakarta RESTful Web Services (or simply Jakarta REST).

When Oracle moved Java EE to the Eclipse Foundation, they retained the trademark on the “Java” name. This forced a massive package migration from javax.ws.rs.* to jakarta.ws.rs.*.

The community didn’t just rename the project; they stripped out legacy dependencies from the early 2000s. For example, recent specifications (like Jakarta REST 4.0) completely decoupled the framework from old JAXB XML requirements and removed obsolete ManagedBeans components. It is now a lean, modern, JSON-first specification that runs natively on virtual threads (Project Loom).

How OpenML Embraces JAX-RS#

So far we have reached the following wrap up:

• Specification: JAX-RS (specifically version 2.1 via JSR 370, now known as Jakarta REST) defines the rules and annotations.
• Traditional Implementation (application server): Jersey
• Modern Implementation (cloud-native): Quarkus

Each OpenML’s Java-based webservice maintains both implementation with a “shared engine strategy” by isolating core business logic and JSR 370 into framework-agnostic Maven module:

• The Core Resource Module

  This module contains purely our JSR 370 resources, utilizing only standard jakarta.ws.rs (or javax.ws.rs) annotations. It has zero awareness of whether Jersey or Quarkus is running it.

  1
  package io.openml.resource;
  2
  
  3
  import jakarta.ws.rs.GET;
  4
  import jakarta.ws.rs.Path;
  5
  import jakarta.ws.rs.Produces;
  6
  import jakarta.ws.rs.core.MediaType;
  7
  
  8
  @Path("/dataset")
  9
  public class DatasetResource {
  10
  
  11
      @GET
  12
      @Produces(MediaType.APPLICATION_JSON)
  13
      public String getDatasetInfo() {
  14
          return "{\"status\": \"active\"}";
  15
      }
  16
  }
  

• The Jersey Bootstrapper Module

  The traditional deployment module of OpenML webservice imports DatasetResource above and spins it up using an embedded Jetty container and Jersey’s ResourceConfig:

  1
  import org.glassfish.jersey.server.ResourceConfig;
  2
  
  3
  public class JerseyApp extends ResourceConfig {
  4
      public JerseyApp() {
  5
          // Register the shared JSR 370 classes manually
  6
          register(io.openml.resource.DatasetResource.class);
  7
      }
  8
  }
  

• The Quarkus Bootstrapper Module

  To run those exact same endpoints inside Quarkus, WE create a parallel deployment module. We pull in the Quarkus REST extension via pom.xml:

  1
  <dependency>
  2
      <groupId>io.quarkus</groupId>
  3
      <artifactId>quarkus-rest</artifactId>
  4
  </dependency>
  5
  <dependency>
  6
      <groupId>io.openml</groupId>
  7
      <artifactId>core-resource-module</artifactId> <!-- Contains DatasetResource -->
  8
      <version>${project.version}</version>
  9
  </dependency>
  

  Quarkus automatically scans application’s classpath at compile-time, locates DatasetResource via its @Path annotation, and hooks it directly into its ultra-fast, reactive HTTP engine (RESTEasy Reactive). We don’t have to alter a single line of application’s endpoint logic; it instantly runs with build-time optimizations.

Handling the Dependency Injection Divide

The biggest friction point we might encounter when maintaining both environments simultaneously is Dependency Injection (DI) because

• Jersey natively relies on the HK2 injection engine (or manual wiring).
• Quarkus strictly relies on its own compile-time CDI implementation called ArC (handling @ApplicationScoped, @Inject, etc.).

To keep OpenML’s backend maintainable across both systems, we must be sure to keep the shared JSR 370 resource classes lean and free of direct DI framework annotations. Use standard constructor injection wherever possible. When running in Jersey, we can manually bind the dependencies in AbstractBinder configuration; when running in Quarkus, ArC will automatically resolve the constructor parameters at compile-time without requiring framework-specific boilerplate.

Jersey for Platform SDK While Spring on Solution Side#

The distinction between Jersey and Spring perfectly mirrors the divide between a composable platform and an out-of-the-box solution.

Jersey represents the platform ethos. As a standard implementation for the JAX-RS specification, it provides a highly focused set of programmatic primitives for mapping Java methods to network endpoints. It does not attempt to manage the entire application lifecycle, dictate the configuration format, or force a specific dependency injection container. Instead, it offers explicit control and strict adherence to open standards, requiring the engineer to act as the architect who wires the web layer into the broader application. It supplies the standard components for defining strict a priori network boundaries (REST/HTTP), but the structural assembly and memory management remain entirely in our hands.

Spring, particularly Spring Boot, embodies the solution paradigm. It is a comprehensive framework designed to deliver a turnkey, fully operational microservice with minimal friction. Through aggressive auto-configuration, opinionated defaults, and embedded servers, it abstracts away the complex wiring. A developer can drop in a few dependencies and a configuration file, and the framework effectively takes over the application lifecycle. While this drastically reduces the time required to get a web service listening on a port, it inherently sacrifices transparency and architectural freedom. It wraps the execution context in its own ecosystem rather than relying on strictly defined, platform-agnostic specifications.

TIP

Evaluating them through this lens makes the architectural trade-offs clear. Utilizing a JAX-RS implementation aligns with a philosophy that values granular boundary control, explicit architectural contracts, and the modularity of a true platform SDK. Conversely, leveraging a comprehensive framework trades that underlying architectural control for the immediate, high-velocity delivery of a pre-configured gateway solution.

From Technical Perspective#

Choosing between Python, Go, and Java for a web service depends heavily on our project’s

• ecosystem requirements
• performance needs, and
• development velocity

Each language shines in distinct architectural scenarios.

From Business Perspective#

Technical elegance is a liability if it compromises a product’s market window, hiring budget, or operational runway. When business constraints dictate the architecture, the decision shifts from technical purity to Time-to-Market (TTM), Total Cost of Ownership (TCO), and talent acquisition.