Agent Skills: REST API

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 |