User Guide

Installation

Add the starter to your project. Ensure you are using Spring Boot 3.2+ and Java 17+.

// build.gradle
dependencies {
    implementation 'dev.ucomprotocol:ucp-spring-boot-starter:1.0.0'
}

Example Application

A fully functional example application is available in the examples/ucp-example directory (of the source repository). This project demonstrates how to configure the library, use the mock adapter, and verify the discovery endpoint.

To run the example:

cd examples/ucp-example
../../gradlew bootRun

Configuration

Configure the library using standard Spring Boot properties in application.properties or application.yml. 

# Default to mock provider for testing
ucp.provider=mock

# Example: Shopify Configuration (Future)
# ucp.provider=shopify
# ucp.endpoint=https://my-store.myshopify.com
# ucp.api-key=shpat_xxxxxxxx

Using the Adapters

Inject the CommerceAdapter bean into your services. This bean automatically resolves to the correct implementation based on your configuration.

Searching Products

@Autowired
private CommerceAdapter commerceAdapter;

public List<Product> search(String term) {
    return commerceAdapter.getCatalogAdapter().searchProducts(term);
}

Managing Carts

public Cart createCartForUser(String userId) {
    return commerceAdapter.getCartAdapter().createCart(userId);
}

Discovery Endpoint

One of the key features of UCP Java is the Automatic Discovery Endpoint. This allows clients to query your service and discover which capabilities it supports (e.g., does it support Carts? Orders?).

How to Enable

To enable the /.well-known/ucp endpoint, you simply need to include the Spring Boot Web starter alongside UCP Java. The library detects if you are running a web application and automatically registers the controller.

// build.gradle
dependencies {
    // 1. Add UCP Java
    implementation 'dev.ucomprotocol:ucp-spring-boot-starter:1.0.0'
    
    // 2. Ensure you have the Web Starter (Discovery only works in web apps)
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

Verification

Once your application starts, you can verify the endpoint is active using curl:

curl http://localhost:8080/.well-known/ucp

Response Example:

GET /.well-known/ucp
{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": [
      {
        "type": "dev.ucp.shopping.catalog",
        "version": "2026-01-23", 
        "spec": "..." 
      },
      { "type": "dev.ucp.shopping.cart", ... },
      { "type": "dev.ucp.shopping.order", ... },
      { "type": "dev.ucp.common.identity", ... }
    ],
    "services": []
  }
}

This response tells you:

Changing Providers

To return a different provider in the discovery info, simply change your configuration in application.properties: 

ucp.provider=shopify

The endpoint will use the Shopify adapter to determine capabilities.

Custom Adapters

To implement your own adapter, simply implement the `CommerceAdapter` interface and register it as a Spring Bean. The auto-configuration will back off and use your bean instead.

@Configuration
public class MyCommerceConfig {
    @Bean
    public CommerceAdapter myCustomAdapter() {
        return new MyCustomCommerceAdapter();
    }
}

Defining Capabilities

The Discovery Endpoint automatically detects which capabilities your adapter supports. It does this by checking which methods return `null`.

For example, if you only support the **Catalog**, you can implement your adapter like this:

public class ReadOnlyCommerceAdapter implements CommerceAdapter {
    
    @Override
    public CatalogAdapter getCatalogAdapter() {
        return new MyCatalogAdapter(); // Supported
    }

    @Override
    public CartAdapter getCartAdapter() {
        return null; // Not Supported
    }

    @Override
    public OrderAdapter getOrderAdapter() {
        return null; // Not Supported
    }

    @Override
    public CustomerAdapter getCustomerAdapter() {
        return null; // Not Supported
    }
}

When you query the discovery endpoint, it will correctly report:

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": [
      {
        "type": "dev.ucp.shopping.catalog",
        ...
      }
    ],
    "services": []
  }
}