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

• 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

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