← Takaisin etusivulle

Hevosrotujen API-dokumentaatio

Tämä avoin JSON-rajapinta palauttaa hevosrotujen tiedot (rodun nimi suomeksi ja englanniksi, lyhenne, säkäkorkeus, värit sekä tieto onko rotu harvinainen) sekä erillisen listan hevosten väreistä lyhenteineen. Rajapinta ei vaadi kirjautumista, ja sille on avattu CORS, joten sitä voi kutsua myös muista verkko-osoitteista (selaimesta suoraan JavaScriptillä) sekä palvelinpuolen sovelluksista (esim. PHP).

Peruspolku (base URL)

Kaikki esimerkit käyttävät sovelluksen omaa osoitetta, korvaa se tarvittaessa oikealla domainilla:

https://esimerkki.example

Endpointit

GET/api/breeds

Hakee rotuja nimen perusteella (suomi tai englanti), tai listaa kaikki rodut jos hakusanaa ei anneta.

Parametri	Pakollinen	Kuvaus
name	Ei	Hakusana. Etsii osittaisena osumana sekä suomen- että englanninkielisestä nimestä (ei kirjainkokoriippuvainen).
exact	Ei	true jos halutaan vaatia täsmällinen (mutta ei kirjainkokoriippuvainen) osuma osittaisen sijaan.

Esimerkkejä:

GET /api/breeds?name=suomen
GET /api/breeds?name=finnhorse&exact=true
GET /api/breeds

GET/api/breeds/<id>

Hakee yhden rodun numeerisen ID:n perusteella.

GET /api/breeds/18

Jos rotua ei löydy, vastaus on 404 ja sisältää {"error": "..."}.

GET/api/colors

Listaa kaikki hevosten värit ja niiden lyhenteet aakkosjärjestyksessä nimen mukaan. Ei parametreja, ei kirjautumista. Vastaus on aina lista.

GET /api/colors

Vastauksen muoto

/api/breeds/<id> palauttaa yhden objektin, /api/breeds palauttaa listan samanmuotoisia objekteja:

{
  "id": 18,
  "name_fi": "Suomenhevonen",
  "name_en": "Finnhorse",
  "abbreviation": "sh",
  "height": "154.9 cm",
  "colors": "Not found",
  "rarity": "ei"
}

Kenttä	Kuvaus
id	Rodun yksilöivä tunniste (numero)
name_fi	Rodun nimi suomeksi
name_en	Rodun nimi englanniksi
abbreviation	Lyhenne
height	Säkäkorkeus
colors	Rodulle tyypilliset värit
rarity	"kyllä" tai "ei" - onko rotu luokiteltu harvinaiseksi

/api/colors palauttaa listan väriobjekteja:

[
  { "id": 25, "name": "cremello", "abbreviation": "cre", "name_en": null, "abbreviation_en": null },
  { "id": 114, "name": "rautias", "abbreviation": "rt",
    "name_en": "Chestnut, sorrel, red (chesnut ainoastaan suffolkinhevosesta)", "abbreviation_en": "ch" }
]

Kenttä	Kuvaus
id	Värin yksilöivä tunniste (numero)
name	Värin nimi suomeksi
abbreviation	Värin lyhenne suomeksi
name_en	Englanninkielinen termi (tai null jos ei tiedossa)
abbreviation_en	Englanninkielinen lyhenne (tai null) — vain muutamalla perusvärillä
updated_by, updated_at	Kuka muokkasi väriä viimeksi ja milloin (tai null)

Esimerkki: curl

curl "https://esimerkki.example/api/breeds?name=suomen"

curl "https://esimerkki.example/api/colors"

Esimerkki: HTML + JavaScript (fetch)

Tämä toimii suoraan selaimessa, myös eri verkkotunnuksesta ladatulla sivulla (CORS on sallittu).

const API_BASE = "https://esimerkki.example";

async function searchBreeds(name) {
  const url = new URL(API_BASE + "/api/breeds");
  if (name) url.searchParams.set("name", name);
  const response = await fetch(url);
  if (!response.ok) throw new Error("API-kutsu epäonnistui: " + response.status);
  return response.json();
}

async function getBreedById(id) {
  const response = await fetch(API_BASE + "/api/breeds/" + id);
  if (response.status === 404) return null;
  if (!response.ok) throw new Error("API-kutsu epäonnistui: " + response.status);
  return response.json();
}

async function getColors() {
  const response = await fetch(API_BASE + "/api/colors");
  if (!response.ok) throw new Error("API-kutsu epäonnistui: " + response.status);
  return response.json(); // [{ id, name, abbreviation }, ...]
}

Esimerkki: PHP

<?php
$apiBase = "https://esimerkki.example";

function fetchJson(string $url): array {
    $context = stream_context_create(["http" => ["method" => "GET", "header" => "Accept: application/json\r\n", "ignore_errors" => true]]);
    $response = file_get_contents($url, false, $context);
    if ($response === false) throw new RuntimeException("API-kutsu epäonnistui: $url");
    return json_decode($response, true) ?? [];
}

$breeds = fetchJson($apiBase . "/api/breeds?name=" . urlencode("suomen"));
foreach ($breeds as $breed) {
    echo $breed["name_fi"] . " (" . $breed["name_en"] . ")" . PHP_EOL;
}

$colors = fetchJson($apiBase . "/api/colors");
foreach ($colors as $color) {
    echo $color["name"] . " = " . $color["abbreviation"] . PHP_EOL;
}

Virhetilanteet

HTTP-koodi	Kuvaus
200	Onnistunut haku (myös jos tulosjoukko on tyhjä lista)
404	/api/breeds/<id>: rotua ei löytynyt annetulla ID:llä