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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportmonks.com/v3/definitions/endpoint-vs-entity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.