AmericaSCORESBayArea / AmericaSCORESBayArea/salesforce-data-api

Update RAML File for Enhanced Error Validation

未关闭
#206 0 条评论 0 个 reaction 已指派 1 人 已被 @a-v25 认领 在 GitHub 查看
Critical/Blocking documentation invalid
主要语言
DataWeave
星标
2
派生
1
PR 合并指标
30 天内没有已合并 PR

描述

### 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.

贡献指南

这个仓库没有索引到贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。