REST API
rest-api
REST API standards for Java Spring services. Covers Bitso API guidelines, authentication integration, OpenAPI documentation, and RFC-37 service documentation. Use when creating or maintaining REST endpoints.
SKILL.md
Full skill instructions
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
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
.cursor/rules/java-rest-api-guidelines.mdc- Full API guidelines.cursor/rules/java-service-documentation.mdc- RFC-37 documentation
Related Skills
| Skill | Purpose |
|---|---|
| grpc-standards | gRPC service standards |
| java-testing | Testing REST endpoints |