AmericaSCORESBayArea / AmericaSCORESBayArea/salesforce-data-api

Update RAML File for Enhanced Error Validation

Aberta
#206 0 comentários 0 reações 1 responsável Reivindicada por @a-v25 Ver no GitHub
Critical/Blocking documentation invalid
Linguagem predominante
DataWeave
Estrelas
2
Forks
1
Métricas de merge de PRs
Nenhum PR com merge em 30d

Descrição

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

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.