AmericaSCORESBayArea / AmericaSCORESBayArea/salesforce-data-api

Update RAML File for Enhanced Error Validation

Ouverte
#206 0 commentaires 0 réactions 1 personne assignée Réclamée par @a-v25 Voir sur GitHub
Critical/Blocking documentation invalid
Langage dominant
DataWeave
Étoiles
2
Forks
1
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

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

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.