# Endpoint vs Entity

### Difference between an Endpoint and an Entity

When working with the Sportmonks Football API, you’ll encounter both **endpoints** and **entities**. These two concepts are closely related but serve different purposes. Understanding the difference between them is key to designing efficient requests and interpreting responses correctly.

#### What is an Endpoint?

An **endpoint** is a **specific API URL** that you call to **retrieve or send data**.\
It defines *where* and *how* you can access the data.

Endpoints:

* Represent **actions** or **data-access points** in the API.
* Are used to make **requests** (GET, POST, etc.) via a structured URL.
* Usually include **filters**, **includes**, and **query parameters** to refine or expand the response.

**Example:**

```
GET /v3/football/fixtures/19101794?api_token=YOUR_TOKEN&include=events,statistics
```

This endpoint retrieves details for a **single fixture**, including related events and statistics.

**Common endpoint examples:**

* `/fixtures` : To get match information.
* `/teams` : To list or look up teams.
* `/players` : To fetch player data.
* `/standings/seasons/{season_id}` : To view a season’s table.

Each endpoint returns one or more **entities**.

#### What is an Entity?

An **entity** represents a **type of data object** that exists within the Sportmonks data model.\
It describes *what* the data is, such as a **Fixture**, **Team**, **Player**, or **League**.

Entities:

* Are **objects** that appear in API responses.
* Have a **consistent structure** (fields, attributes, and relationships).
* Are often **linked to one another** (for example, a Fixture includes Team and Venue entities).

**Example Entity Structure (Fixture):**

```json
{
  "id": 19101794,
  "name": "Borussia Dortmund vs Real Madrid",
  "starting_at": "2024-06-01 19:00:00",
  "venue": {
    "id": 1,
    "name": "Wembley Stadium",
    "city": "London"
  },
  "participants": [
    { "id": 68, "name": "Borussia Dortmund" },
    { "id": 3468, "name": "Real Madrid" }
  ]
}
```

Here, the **Fixture entity** contains **Venue** and **Team (Participant)** entities as nested objects.

#### The relationship between Endpoints and Entities

You can think of it like this:

| Concept      | Purpose                                          | Example                                                         |
| ------------ | ------------------------------------------------ | --------------------------------------------------------------- |
| **Endpoint** | The URL you call to get or send data             | `/fixtures/19101794`                                            |
| **Entity**   | The data structure returned by the endpoint      | `Fixture`, which includes `Team`, `Venue`, and `Event` entities |
| **Analogy**  | Endpoint = door handle, Entity = the room inside | The handle lets you enter, but the room contains the data       |

***

#### Examples from the Football API

* Calling the **Fixtures endpoint** returns **Fixture entities**.
* Calling the **Teams endpoint** returns **Team entities**.
* Including `statistics` or `lineups` in your query adds **Statistic** or **Lineup entities** to the response.
* Calling the **Standings endpoint** returns **Standing entities**, often containing nested **Team** and **League** data.

**Example combined request:**

```
GET /v3/football/fixtures?include=participants,venue,statistics
```

This single **endpoint** returns multiple **entities** (Fixture, Team, Venue, Statistic).

#### Why the distinction matters

* **Documentation navigation**: Each endpoint page tells you how to *get* the data. Each entity page tells you *what fields* you’ll receive.
* **Database design**: Understanding entities helps when modelling your local storage schema.
* **Includes and relations**: You’ll often “include” extra entities within an endpoint call. Knowing their structure ensures efficient queries.

#### Summary

| Term             | Description                                              | Example                                                                                |
| ---------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Endpoint**     | A path you call in the API to request or send data       | `/v3/football/fixtures/19101794`                                                       |
| **Entity**       | The object type representing actual data in the response | `Fixture`, `Team`, `Player`, `League`                                                  |
| **Relationship** | Endpoints deliver entities                               | The Fixtures endpoint returns Fixture entities (which can include Teams, Venues, etc.) |