AmericaSCORESBayArea / AmericaSCORESBayArea/salesforce-data-api

Update RAML File for Enhanced Error Validation

Đang mở
#206 0 bình luận 0 reaction 1 người được giao Được @a-v25 nhận Xem trên GitHub
Critical/Blocking documentation invalid
Ngôn ngữ chính
DataWeave
Star
2
Fork
1
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

### Preparation
- [x] - [x] Once #205 is closed, RAML file needs to be updated to accurately describe all APIs to return proper error responses to the client.

### Validate all endpoints under the given root path:

@AleksandrMolchagin:
- [ ] `/assessments` (2) #248
- [ ] `/useraccount` (1) #249

@TharunKumarReddyPolu:
- [x] `/contacts` (8) #250
- [x] `/waivers` (3) #251
- [x] `/teams` (3) #252
- [x] `/attendances` (1) #253

@nismail1:
- [x] `/coach` (11) #254
- [x] `/regions` (3) #255
- [x] `/seasons` (2) #256

@ERICEX2025 :
- [ ] `/sessions` (7) #257
- [ ] `/enrollments` (5) #258
- [ ] `/teamSeasons`(4) #259

The number in parentheses indicate the number of endpoints under its root path. For example, the root path `sessions` has 7 endpoints. The number can be wrong.

### Instructions

We need to test all the endpoints related to `/${root_path}` to ensure they are working correctly and update the corresponding RAML files to enable proper validation. The steps include:

1. **Identify and List Endpoints**:
- [ ] Identify all `/${root_path}` endpoints in `${root_path}.xml`
- [ ] Compare your list with the provided Postman collection and ensure all endpoints are accounted for

2. **Testing Endpoints**:
- [ ] Use Postman, Thunder or similar tools to test each endpoint.
- [ ] Save testing information for future reference (we will be updating them)
- [ ] Document the response status codes and response bodies
- [ ] _If endpoint is not implemented_, create a new ticket in [this project](https://github.com/orgs/AmericaSCORESBayArea/projects/5) (you don't have to close it)

3. **Update RAML Files**:
- [ ] Ensure the RAML files for `/${root_path}` are up-to-date and each endpoint includes:
- displayName
- description
- queryParameters (if present)
- body (typically, `application/json`, if present)
- responses

4. **Maintain Response Table**:
- [ ] Create a table to document the responses and their meanings for the application. This table should include:
- Endpoint URL
- HTTP Method
- Response Status Code
- Response Body
- Description of the response

**Resources**:
- Postman Collection: `docs/Scores - Salesforce Data API.postman_collection.json`
- Current RAML File: `src/main/resources/api/salesforce-data-api.raml`

**Examples of good RAML specifications:**

1. **searchByPhoneNumber**
```raml
/searchByPhoneNumber:
get:
displayName: Get matching contacts for a given phone number
description: Get contacts matching a search string with a phone number (to be used for Student contacts for now)
queryParameters:
phoneNumber:
displayName: phoneNumber
description: Phone number
type: string
required: true
pattern: '^\+?[1-9]\d{1,14}$' # E.164 international phone number format
responses:
200:
body:
application/json:
type: types.Contact[]
400:
body:
application/json:
example:
message: Invalid phone number format. The phone number must be in E.164 format.
```

```raml
/sessions
/{sessionId}
patch:
displayName: Update session
description: Update session fields for the given ID
body:
application/json:
type: types.SessionUpdateModel
responses:
200:
body:
application/json:
example:
message: Session updated
400:
body:
application/json:
example:
message: Bad request
404:
body:
application/json:
example:
message: Session not found
```

**Acceptance Criteria**:
- All `/${root_path}` endpoints are tested and documented.
- RAML files are updated to reflect the correct endpoints and validation.
- A comprehensive table of responses and their meanings is created.
- New tickets are created for any missing or unimplemented endpoints.

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.