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
Quick Start
Authentication
Documentation
References
Related Rules
Related Skills

Available Resources

📚 references/ - Detailed documentation

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

Reference	Description
references/guidelines.md	API guidelines, authentication, testing
references/documentation.md	RFC-37 documentation standards

Related Rules

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

Related Skills

Skill	Purpose
grpc-services-rfc-33	gRPC service standards
java-testing	Testing REST endpoints

rest-api