REST API

REST API standards for Java Spring services.

When to use this skill

• Creating REST endpoints in Spring services
• Integrating Bitso authentication
• Documenting APIs with OpenAPI
• Setting up service documentation (RFC-37)
• Testing authenticated endpoints

Skill Contents

Sections

• When to use this skill (L24-L31)
• Quick Start (L52-L91)
• Authentication (L92-L123)
• Documentation (L124-L144)
• References (L145-L151)
• Related Rules (L152-L156)
• Related Skills (L157-L162)

Available Resources

📚 references/ – Detailed documentation

• documentation
• guidelines

Quick Start

1. Add Authentication Dependency

implementation libs.bitso.api.base.spring.webapi

2. Configure gRPC Client

grpc:
  client:
    user-security:
      address: dns:/${USER_SECURITY_HOST:localhost}:${GRPC_PORT:8201}
      negotiation-type: PLAINTEXT

3. Create Controller

@RestController
@RequestMapping("/")
public class MyController {

    @Autowired
    SpringHttpResponseFactory responseFactory;

    @Autowired
    WebAuthenticationContext authenticationContext;

    @GetMapping("/private")
    @WebAPI(WebAPIType.PRIVATE)
    public ResponseEntity<?> privateEndpoint() {
        Long userId = authenticationContext.getPrincipalId();
        return responseFactory.ok(userId);
    }
}

Authentication

Configuration Bean

@Configuration
public class UserSecurityContextConfiguration {
    @Bean
    @Primary
    public AuthenticationService authenticationService(
        @GrpcClient("user-security") AuthorizationServiceV1BlockingStub stub,
        @Qualifier("userSecurityResilienceConfig") ResilienceConfiguration config
    ) {
        return new ProtoShimAuthenticationService(config, stub);
    }
}

Component Scan

Ensure your main application scans Bitso components:

@SpringBootApplication
@ComponentScan("com.bitso.*")
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Documentation

OpenAPI Specification

All endpoints should be documented under ./docs/api/rest/openapi.yaml

RFC-37 Documentation Structure

docs/
├── api/
│   ├── async/
│   ├── grpc/
│   └── rest/
├── decisions/
├── <domain-name>/
├── runbooks/
└── how-tos/
    └── local-execution.md

References

Related Rules

• java-rest-api-guidelines – Full API guidelines
• java-service-documentation – RFC-37 documentation

Related Skills