Changelog

All notable changes to the WPPR API will be documented here.

[1.1.0] - 2025-11-27

Breaking Changes

🚨 Pagination Removed from Player Search

Endpoint: GET /v1/players/search/by-name

The page and limit query parameters have been removed. The endpoint now returns all matching results without pagination.

Before:

GET /v1/players/search/by-name?name=john&page=1&limit=20

After:

GET /v1/players/search/by-name?name=john

Migration Steps:

• Remove page and limit parameters from your search requests
• Handle the full result set in your application
• Implement client-side pagination if needed

---

🚨 Categories Response Schema Changed

Endpoint: GET /v1/categories/list

The color field has been removed and replaced with a description field.

Old Response:

{
  "name": "C+, B-",
  "range": "3.750 - 4.749",
  "category": "Expert",
  "color": "bg-amber-500",
  "min": 3.75,
  "max": 4.749
}

New Response:

{
  "name": "C+",
  "range": "3.750 - 4.249",
  "category": "Expert",
  "description": "Controlled on court, basic tactics",
  "min": 3.75,
  "max": 4.249
}

Migration Steps:

• Remove any code that depends on the color field
• Implement your own color mapping if needed for UI
• Use the new description field for enhanced user experience

---

Added

Enhanced Error Response Documentation

All endpoints now return standardized, well-documented error responses:

{
  "error": true,
  "message": "Descriptive error message",
  "statusCode": 401
}

Documented HTTP Status Codes:

• 400 - Bad Request (invalid query parameters)
• 401 - Unauthorized (missing or invalid API key)
• 404 - Not Found (player or resource not found)
• 500 - Internal Server Error
• 503 - Service Unavailable (upstream service issues)

Benefits:

• More predictable error handling
• Better debugging with consistent error messages
• Improved client-side error handling logic

---

Phone Number Format Documentation

Endpoint: GET /v1/players/search/by-phone/{phonenumber}

Enhanced documentation for supported phone number formats:

Supported Formats:

• 971501234567 (standard)
• +971501234567 (with plus prefix)
• 00971501234567 (with 00 prefix)
• 971-50-123-4567 (with dashes)
• 971 50 123 4567 (with spaces)

Benefits:

• Clearer documentation of accepted formats
• Reduces integration errors
• Better developer experience

---

Comprehensive Property Descriptions

All response properties now include detailed descriptions in the OpenAPI specification:

Player Response Properties:

• id - "Player WPPR profile ID"
• wppr_id - "WPPR profile identifier"
• wppr_profile_url - "URL to the player profile on WeCourts"
• display_name - "Player display name"
• rating - "Current WPPR rating"
• rating_category_name - "Rating category name"
• rating_status - "Rating status (e.g., AR for Active Rating)"
• nationality - "Nationality ISO2 country code"
• gender - "Gender code" (enum: ["M", "F"])
• And many more...

Benefits:

• Self-documenting API responses
• Clearer field purposes and formats
• Better TypeScript/type generation support

---

Schema Requirements

All response schemas now explicitly define required fields using the required array.

Example:

{
  "required": ["id", "wppr_id", "wppr_profile_url", "display_name", "rating_status"]
}

Benefits:

• Know which fields are always present
• Better TypeScript/type generation
• More reliable client-side code

---

Changed

Player Rating Endpoint Description

Endpoint: GET /v1/players/{wppr_id}/rating

• Old description: "Retrieves the current rating and ranking information for a player from their WPPR profile."
• New description: "Retrieves the current rating and rating status and rating category for a player from their WPPR profile."

This clarifies that the endpoint returns rating, status, and category information (not ranking).

---

Match Response Documentation

Endpoint: GET /v1/players/{wppr_id}/matches

All nested match properties now have detailed descriptions:

Match Properties:

• match_id - "Match ID"
• date - "Match date in ISO format"
• display_date - "Human-readable match date"

Team Properties:

• team_1 / team_2 - "First team" / "Second team"
• won - "Whether this team won the match"
• set_1 / set_2 / set_3 - Score information with nullable indicators

Benefits:

• Better understanding of complex match data structure
• Easier to build match display UI
• Clear indication of nullable fields

---

[1.0.0] - 2025-11-11

Added

Players API

• GET /v1/players/:wppr_id - Get player information
• GET /v1/players/:wppr_id/rating - Get player rating from WPPR profile
• GET /v1/players/:wppr_id/matches - Get player match history
• GET /v1/players/:wppr_id/stats - Get player statistics

Technical Details

• Base URL: https://developers.wecourts.com/api
• OpenAPI: 3.0

---

Version History

Version	Release Date	Status	Notes
1.1.0	2025-11-27	✅ Current	Enhanced docs, breaking changes
1.0.0	2025-11-11	Deprecated	Initial release

---

Support

If you have questions or encounter issues:

• Email: [email protected]
• Support Portal: WeCourts Support