Rajapintaviite

https://api.huuto.net/1.1/

Vastaukset ovat JSONia ja UTF-8-merkistöä. Hinnat ovat euroja JSON-lukuina, esimerkiksi 19.9 tai 18. Loppunollat jäävät pois.

Kokeile turvallisesti

Luonnos ja esikatselussa oleva ilmoitus eivät näy ostajille. Kokeile kutsuja niillä ja poista ilmoitus lopuksi kutsulla DELETE.

Kutsut

Ryhmä	Kutsut
Kirjautuminen	POST /authentication DELETE /authentication
Ilmoitukset	POST /items GET /items/{id} PUT /items/{id} DELETE /items/{id}
Kuvat	GET /items/{id}/images GET /items/{id}/images/{imageId} POST /items/{id}/images DELETE /items/{id}/images/{imageId}
Myynnit	GET /users/{id}/sales GET /items/{id}/purchases GET /purchases/{sellerId}/items/{itemId}/htur-label
Osastot	GET /categories GET /categories/{id} GET /categories/{id}/subcategories GET /categories/{id}/items
Käyttäjät	GET /users/{id} GET /users/{id}/settings GET /users/{id}/feedbacks GET /users/{id}/purchases GET /users/{id}/favorites
Muut	Huudot, Osta heti, hintaehdotukset, kysymykset

HTUR on Huutoturvan lyhenne kenttien ja osoitteiden nimissä, esimerkiksi hturPackageCode ja htur-label.

Tunnistautuminen

Lähetä token otsakkeessa jokaisessa kutsussa. Token saadaan kirjautumalla.

X-HuutoApiToken: 1e0bb382298a103578b2801527b4dbca

Versio 2.0

Tulevassa versiossa 2.0 kaikki kutsut vaativat tokenin. Lähetä se jo nyt myös julkisissa kutsuissa.

Vanhentunut token

Vanhentunut tai tuntematon token palauttaa 401 myös julkisessa kutsussa. Kirjaudu uudelleen tai jätä otsake pois.

Pyynnön runko

Lähetä luonti- ja muokkauskutsut JSONina otsakkeella Content-Type: application/json. Poikkeukset:

• Kirjautuminen ja kysymyksen lähetys ovat lomakemuotoisia.
• Kuvan lähetys on multipart/form-data.

Virheet

Useimmat kutsut palauttavat virheen tässä muodossa. field ja code ovat mukana vain osassa virheistä.

{
  "errors": [
    {
      "field": "status",
      "code": "IDENTIFICATION_REQUIRED",
      "messages": ["Ilmoituksen julkaiseminen edellyttää tunnistautumista. …"]
    }
  ]
}

Kutsu	Virheen muoto
Useimmat	{"errors": [{"field", "code", "messages"}]}
Osta heti ja huuto	{"error", "message"}
Osoitekortti	{"success": false, "error", "message"}, message vain osassa

Viestit voivat olla suomeksi tai englanniksi, joten tee logiikka tilakoodin, kentän field ja kentän code varaan.

Tila	Merkitys
200	Onnistui
201	Luotiin
204	Onnistui, ei sisältöä
400	Virheellinen pyyntö tai validointivirhe
401	Token on tuntematon tai vanhentunut, myös julkisessa kutsussa, tai osoitteen käyttäjä-id ei ole tokenin käyttäjä
403	Token puuttuu kutsusta, joka vaatii sen, tai resurssi ei ole sinun
404	Resurssia ei löydy
409	Resurssi ei ole vielä valmis, tai osto on ristiriidassa toisen oston kanssa
429	Liian monta Osta heti -kutsua lyhyessä ajassa
500	Odottamaton virhe
502	Taustapalvelu ei vastannut, yritä myöhemmin uudelleen

Huomaa 401 ja 403

Merkitykset poikkeavat tavallisesta käytännöstä: puuttuva token on 403 ja virheellinen token 401. Poikkeus on Osta heti, joka palauttaa puuttuvasta tokenista 401 ja tuntemattomasta 403.

Päivitysviive

Hakukutsujen vastaukset voivat olla hetken vanhoja. Oma muutos näkyy omassa ilmoituksessa ja myyntilistassa heti.

Kutsu	Viive enintään
GET /items/{id}, GET /items/{id}/purchases, GET /categories/{id}/items	1 min
GET /users/{id}/sales	2 min
GET /users/{id}/feedbacks, /purchases, /favorites	30 min, ostot tilalla processing 10 s
GET /users/{id}	1 h, omat tiedot 15 s
GET /users/{id}/settings	1 h
GET /categories, /categories/{id}, /categories/{id}/subcategories	1 h

Kutsutiheys

Kirjaudu kerran ja käytä tokenia koko sen voimassaolon ajan. Älä kysele rajapintaa tiheämmin kuin vastaukset päivittyvät.