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'
}

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
{
  "ucpVersion": "1.0",
  "provider": "mock",
  "capabilities": [
    "catalog",
    "cart",
    "order",
    "customer"
  ]
}

This response tells you:

• Protocol Version: 1.0
• Provider: You are currently using the "mock" provider (default).
• Capabilities: The current adapter supports catalog browsing, cart management, ordering, and customer management.

Changing Providers

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

ucp.provider=shopify

The endpoint will immediately reflect this change:

{
  "ucpVersion": "1.0",
  "provider": "shopify",
  ...
}

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();
    }
}