eclipse-tractusx / eclipse-tractusx/bpdm
Pool: Document HTTP response codes according to CX-0012
- Dominant language
- Kotlin
- Stars
- 12
- Forks
- 28
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 41
Description
### Description
**As** a conformity assessor evaluating CX-0012 compliance,
**I want** all Pool API endpoints to document HTTP response codes 200, 400, 401, 403, 404, and 500 in their OpenAPI specification,
**so that** the generated OpenAPI spec satisfies the MUST requirement in CX-0012 §2.2.4 and can be used as proof of conformity.
CX-0012 §2.2.4 states: *"The following http response codes MUST be defined for all resources: 200 - OK, 400 - Bad Request, 401 - Unauthorized, 403 - Forbidden, 404 - Not Found, 500 - Internal Server Error."*
Currently, all Pool API endpoint interfaces (`PoolLegalEntityApi`, `PoolSiteApi`, `PoolAddressApi`, `PoolMetadataApi`, `PoolChangelogApi`, `PoolBpnApi`, `PoolMembersApi`) are missing `@ApiResponse` annotations for 401, 403, and 500. Some endpoints also omit 404 where applicable. This means the generated OpenAPI specification does not document these required response codes, making the implementation non-conformant with the standard's conformity proof requirement.
### Acceptance Criteria
- [ ] Every endpoint in `PoolLegalEntityApi` includes `@ApiResponse` entries for 200, 400, 401, 403, and 500 at minimum; 404 is added where a single resource is looked up by identifier
- [ ] Every endpoint in `PoolSiteApi` includes `@ApiResponse` entries for 200, 400, 401, 403, and 500 at minimum; 404 is added where a single resource is looked up by BPNS
- [ ] Every endpoint in `PoolAddressApi` includes `@ApiResponse` entries for 200, 400, 401, 403, and 500 at minimum; 404 is added where a single resource is looked up by BPNA
- [ ] Every endpoint in `PoolMetadataApi` includes `@ApiResponse` entries for 200, 400, 401, 403, and 500 at minimum
- [ ] Every endpoint in `PoolChangelogApi` includes `@ApiResponse` entries for 200, 400, 401, 403, and 500 at minimum
- [ ] Every endpoint in `PoolBpnApi` includes `@ApiResponse` entries for 200, 400, 401, 403, and 500 at minimum
- [ ] Every endpoint in `PoolMembersApi` includes `@ApiResponse` entries for 200, 400, 401, 403, and 500 at minimum
- [ ] The generated OpenAPI specification reflects all required status codes for each resource
### Additional Information
Reference: CX-0012 §2.2.4 Error Handling.
The IANA HTTP Status Code Registry must be consulted for the decision on when to use which error code, per the standard. The descriptions for 401/403/500 annotations should follow the Spring Security behavior already in place: 401 for missing/invalid credentials, 403 for insufficient permissions, 500 for unexpected server-side failures.
Contributor guide
Assessment
This issue has not been assessed yet.