eclipse-tractusx / eclipse-tractusx/bpdm

Pool: Document HTTP response codes according to CX-0012

Open
#1,684 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.