AmericaSCORESBayArea / AmericaSCORESBayArea/salesforce-data-api

Update RAML File for Enhanced Error Validation

Open
#206 0 comments 0 reactions 1 assignee Claimed by @a-v25 View on GitHub
Critical/Blocking documentation invalid
Dominant language
DataWeave
Stars
2
Forks
1
PR merge metrics
No merged PRs in 30d

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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.