# API

## Co API umí?

* Zobrazení všech veřejně dostupných informací o serveru
* Seznam hráčů hlasujících pro server za posledních 30 dní
* Aktuální počet hlasů
* Status a další informace serveru (ip adresa, port, motd, verze, mód, hráči/sloty)
* Detailní statistiky - <https://mcservery.eu/stats>

{% hint style="danger" %}
Nikomu nesdělujte ani neposílejte svůj API klíč. V případě vyzrazení vygenerujte nový – původní přestane být funkční.
{% endhint %}

## Jak API používat?

### **Získání klíče**

Pro používání api je nutné vygenerovat api key který vám zajistí přístup k informacím pro server se kterým je klíč navázaný. Klíč vygenerujete po přihlášení k účtu který je spojený s daným serverem. Je nutné být přihlášený na <http://mcservery.eu/login.php>

Pro vygenerování klíče si po přihlášení k Vašemu zobrazte detail Vámi přidaného serveru.&#x20;

Pod popisem serveru naleznete box s názvem „Upravit server“. Zde stačí kliknout na tlačítko vygenerovat api key.

<figure><img src="/files/0JTmS6sImFLDudnJP5QJ" alt=""><figcaption></figcaption></figure>

### Rate limit

Rate limit je maximální počet API volání, které aplikace nebo uživatel může v určitém časovém období provést. Pokud je tento limit překročen, dojde k zablokování požadavků.

#### Proč limitujeme počty požadavků?

Je to běžnou praxí pro API a limity jsou zavedeny z několika důvodů:

* **Pomáhají chránit API proti zneužití nebo nesprávnému použití.** Například útočník by mohl zaplavit API požadavky v pokusu o přetížení serveru.
* **Limity pomáhají zajistit, že každý má spravedlivý přístup k API.** Pokud jedna osoba nebo aplikace provede nadměrný počet požadavků, mohlo by to zpomalit API pro všechny ostatní.

#### Jaké limity jsou nastaveny?

Maximum je **10 požadavků** během **10 vteřin.**

#### Co se stane pokud limit překročím?

Dojde k blokaci IP adresy ze které jsou požadavky odesílaný. **Blokace trvá 10 vteřin.**

Pokud narazíte na chybu **429** nebo **1015**, znamená to, že jste v krátkém časovém období provedli příliš mnoho požadavků a API odmítá plnit další požadavky, dokud neuplyne stanovené časové období.

**Stejné limity se vztahují i na přístup na web, tedy ne jen na API požadavky jako takové.**

## API reference

### Základní informace o serveru

### Hlasování

## Hlasující hráči za posledních 30 dní

<mark style="color:blue;">`GET`</mark> `http://api.mcservery.eu/players/?api_key=`

Zobrazí jednotlivé hlasy podle uživatelského jména a času kdy byl hlas udělen.

#### Query Parameters

| Name                                       | Type   | Description          |
| ------------------------------------------ | ------ | -------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | Klíč pro daný server |

{% tabs %}
{% tab title="200: OK Code 1: Je vyžadován API key" %}

```javascript
{
    'code'    => 1,
    'message' => 'Je vyžadován API key, dokumentaci naleznete na: https://github.com/McServery/API-Dokumentace'
}
```

{% endtab %}

{% tab title="200: OK Code 2: API key je neplatný" %}

```javascript
{
    'code'    => 2,
    'message' => 'API key je neplatný'
}
```

{% endtab %}

{% tab title="200: OK " %}

```javascript
{ 
  "username": "ArtyomCZ", "time": "2020-08-25 18:38:00"
}
```

{% endtab %}

{% tab title="429: Too Many Requests Rate limit" %}

{% endtab %}
{% endtabs %}

## Počet hlasů

<mark style="color:blue;">`GET`</mark> `http://api.mcservery.eu/votes/?api_key=`

Zobrazí počet hlasů pro daný server.

#### Query Parameters

| Name                                       | Type   | Description          |
| ------------------------------------------ | ------ | -------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | Klíč pro daný server |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "Votes": "1"
}
```

{% endtab %}

{% tab title="200: OK Code 2: API key je neplatný" %}

```javascript
{
    'code'    => 2,
    'message' => 'API key je neplatný'
}
```

{% endtab %}

{% tab title="200: OK Code 1: Je vyžadován API key" %}

```javascript
{
    'code'    => 1,
    'message' => 'Je vyžadován API key, dokumentaci naleznete na: https://github.com/McServery/API-Dokumentace'
}
```

{% endtab %}

{% tab title="429: Too Many Requests Rate limit" %}

{% endtab %}
{% endtabs %}

{% embed url="<https://mcservery.eu/blog/mcservery-api-zebricek-hlasujicich-pro-vas-server/>" %}
Pomocí endpointu /players/ lze vytvořit žebříček hlasujících pro Váš server.
{% endembed %}

### Status serveru

## Status serveru

<mark style="color:blue;">`GET`</mark> `http://api.mcservery.eu/status/?api_key=`

#### Query Parameters

| Name                                       | Type   | Description |
| ------------------------------------------ | ------ | ----------- |
| api\_key<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="200: OK Zobrazí aktuální status serveru" %}

{% endtab %}

{% tab title="200: OK Code 1: Je vyžadován API key" %}

```javascript
{
    'code' => 1, 
    'message' => 'Je vyžadován API key, dokumentaci naleznete na: https://github.com/McServery/API-Dokumentace'
}
```

{% endtab %}

{% tab title="200: OK Code 2: API key je neplatný" %}

```javascript
{
    'code' => 2,
    'message' => 'API key je neplatný'
}
```

{% endtab %}

{% tab title="200: OK Code 3: Server offline" %}

```javascript
{
    'code' => 3,
    'message' => 'Server offline'
}
```

{% endtab %}

{% tab title="429: Too Many Requests Rate limit" %}

{% endtab %}
{% endtabs %}

## Související články

{% content-ref url="/pages/FrfSwrytzGBfEoxLDgH6" %}
[Přidání nového serveru](/spravci-serveru/pr-idani-noveho-serveru.md)
{% endcontent-ref %}

**Něco nám uniklo?**

Nebojte se! Rádi poradíme na [Discordu](https://discord.mcservery.eu) nebo <info@mcservery.eu> ✌️


---

# 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://help.mcservery.eu/spravci-serveru/api.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.