# KRKplaysTennis API

> The KRKplaysTennis API rates amateur tennis players in Kraków from the results of the matches they play.

Source: https://saverio-cirillo.com/krk-plays-tennis-api/

The KRKplaysTennis API rates amateur tennis players in Kraków from the results of league and tournament matches. Use it to show players their rating, explain why it changed, suggest fair opponents, or submit results for a competition you run.

> **A fictional API**
>
> KRKplaysTennis is a fictional API, built as a technical writing portfolio. The players, venues, and competitions are invented. You can run every example in these docs against a local mock server.

## How ratings work

* A new player picks a starting level on the [NTRP self-rating scale](https://www.usta.com/en/home/coach-organize/tennis-tool-center/run-usta-programs/national/understanding-ntrp-ratings.html), from 1.5 to 5.5. The API converts it to a starting rating between 1000 and 1800.
* Each rated match moves the rating up or down, based on the result and on the opponent’s rating.
* A confidence value from 0 to 100 shows how settled the rating is. A new rating moves quickly, and a settled rating moves slowly.

The rating comes from results, not from the self-assessment. The self-assessed level is only the starting point. For the full model, with worked examples, see [How ratings work](https://saverio-cirillo.com/krk-plays-tennis-api/concepts/how-ratings-work/).

## What you can do

| Task                                              | Guide                                                                            | Operations                                                                                                                                                                                                                        |
| ------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read player profiles and ratings                  | [Quickstart](https://saverio-cirillo.com/krk-plays-tennis-api/quickstart/)                                  | [List players](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/listplayers/), [Get a player’s rating](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/getplayerrating/)                                                                     |
| See why a rating changed                          | [Explain a rating change](https://saverio-cirillo.com/krk-plays-tennis-api/guides/explain-a-rating-change/) | [List a player’s rating history](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/listplayerratinghistory/)                                                                                                                             |
| Find opponents for a player                       | [Find opponents for a player](https://saverio-cirillo.com/krk-plays-tennis-api/guides/find-opponents/)      | [List match suggestions](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/listmatchsuggestions/)                                                                                                                                        |
| Browse competitions, venues, and results          |                                                                                  | [List competitions](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/listcompetitions/), [List venues](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/listvenues/), [List matches](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/listmatches/) |
| Submit a match result, as a competition organizer | [Submit a match result](https://saverio-cirillo.com/krk-plays-tennis-api/guides/submit-a-match-result/)     | [Submit a match result](https://saverio-cirillo.com/krk-plays-tennis-api/reference/operations/creatematch/)                                                                                                                                                  |

## Which credential you need

| To                   | You need                                                 | Guide                                                                         |
| -------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Read any data        | An API key                                               | [Authenticate with an API key](https://saverio-cirillo.com/krk-plays-tennis-api/authentication/api-key/) |
| Submit match results | An OAuth 2.0 access token with the `matches:write` scope | [Get an access token](https://saverio-cirillo.com/krk-plays-tennis-api/authentication/access-token/)     |

## Conventions

* **Base URL:** `https://api.krkplaystennis.example/v1`
* **Format:** requests and responses are JSON.
* **Pagination:** list operations return `data` and a `next_cursor`. Pass `next_cursor` as `cursor` to get the next page.
* **Errors:** every error is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details object, with a `type` URL for each kind of error. See [Errors](https://saverio-cirillo.com/krk-plays-tennis-api/errors/).
* **Times:** timestamps follow RFC 3339. Availability windows use local time in Kraków (`Europe/Warsaw`).

## Next steps

* [Quickstart](https://saverio-cirillo.com/krk-plays-tennis-api/quickstart/): Start the mock and make your first request in under 5 minutes.
* [Authenticate with an API key](https://saverio-cirillo.com/krk-plays-tennis-api/authentication/api-key/): Send your API key with every read request.
* [Submit a match result](https://saverio-cirillo.com/krk-plays-tennis-api/guides/submit-a-match-result/): Send a result as a competition organizer and check that it's rated.
* [API reference](https://saverio-cirillo.com/krk-plays-tennis-api/reference/): Every operation, parameter, and schema, generated from the OpenAPI spec.