Programsko sučelje aplikacije (API)

Na ovoj stranici

Ova je stranica namijenjena razvojnim timovima koji svoje sustave za pisanje i uređivanje tekstova žele opremiti provjerom pravopisa i gramatike ispravi.me. Svoj tekst možete provjeriti na naslovnoj stranici usluge.

Provjera koju nudi naše sučelje jednaka je onoj koju koristi i stranica ispravi.me: šaljete tekst, a dobivate popis pronađenih pogrešaka s točnim položajem u tekstu, vrstom pogreške, prijedlozima ispravka i kratkim objašnjenjem.

Ukratko

Stalna veza (WebSocket)Pojedinačni zahtjev (HTTPS)
Adresawss://ispravi.me/ispravihttps://ispravi.me/api/ispravi (metoda POST)
Vezajedna veza, mnogo provjerajedan zahtjev, jedna provjera
Pogodno zauređivače u kojima autor piše i često provjeravapovremene provjere, npr. prije objave
Povratna informacijaporuka correction kroz istu vezuPOST https://ispravi.me/api/acceptUserInput

Oba načina koriste isti postupak provjere i vraćaju iste rezultate. Sve su poruke u formatu JSON, kodirane u UTF-8.

Pristup i ograničenja

  • Nema ključeva ni lozinki. Razina korištenja određuje se prema mrežnoj adresi s koje se spajate, jednako kao za korisnike stranice. Organizacije koje s nama surađuju prepoznajemo prema njihovim mrežnim adresama. Ako se vaš poslužitelj nalazi izvan mreže vaše organizacije, na primjer u podatkovnom centru, javite nam njegovu adresu.
  • Ograničenja. Vrijede ista ograničenja kao za korisnike stranice s iste mreže: broj zahtjeva i riječi dnevno, broj zahtjeva u minuti te, za organizacije, zajedničko ograničenje svih korisnika s njihove mreže (Razine korištenja i ograničenja). Trenutačno stanje dobivate u svakom odgovoru (request.user.limits, a za organizacije i request.user.org). Neograničena vrijednost ima null umjesto broja.
  • Veličina teksta. Najmanje tri slova (limits.min_letters; razmaci, brojke i interpunkcija se ne broje), najviše 350 000 znakova, a cijela poruka najviše 768 kB. Gramatička analiza radi za tekstove do 125 000 znakova; dulji tekst dobiva provjeru bez gramatike (odgovor tada sadrži response.grammar s "checked": false), pa vrlo duge dokumente šaljite u dijelovima, po odlomcima ili poglavljima.
  • Istodobni zahtjevi. S jedne adrese mogu istodobno čekati odgovor najviše dva zahtjeva; ostali dobivaju pogrešku 429.
  • Spajanje iz preglednika. Spajate li se iz web-aplikacije koja radi u pregledniku na vašoj domeni, tu domenu moramo dodati na popis dopuštenih. Za spajanje s poslužitelja to nije potrebno.
  • Polje app. Upišite naziv svojeg sustava (npr. "RedakcijaCMS"). Polje više nije ključ, ali nam pomaže razlikovati promet pojedinih sustava.

Kako dobiti pristup

Za većinu sustava nije potrebno ništa: spojite se i šaljite zahtjeve. Javite nam se na ispravi@ispravi.me ako:

  • vaš poslužitelj radi izvan mreže vaše organizacije (na primjer u podatkovnom centru), pa ga trebamo pridružiti vašoj organizaciji;
  • se spajate iz web-aplikacije u pregledniku, pa vašu domenu trebamo dodati na popis dopuštenih;
  • vam treba veći opseg od ograničenja vaše razine.

U poruci ukratko opišite svoj sustav i otprilike koliko teksta planirate provjeravati.

Stalna veza (WebSocket)

  1. Otvorite vezu prema wss://ispravi.me/ispravi.
  2. Poslužitelj odmah šalje poruku session_init s razinom korištenja i ograničenjima.
  3. Šaljete poruke check, jednu ili više njih zaredom.
  4. Na svaku dobivate check_response. Odgovori mogu stići drugim redoslijedom, pa ih povezujete prema polju request_id, koje sami zadajete i koje se vraća nepromijenjeno.
  5. Kad korisnik prihvati prijedlog, možete poslati poruku correction.

Veza ostaje otvorena i nakon pogreške te je možete koristiti dalje.

Zahtjev za provjeru:

{
  "type": "check",
  "request_id": "r-1715780000000-a4f2",
  "text": "Ovo je primjerni tekts za provjeravanje.",
  "context": true,
  "punctuation": true,
  "showinfo": true,
  "app": "RedakcijaCMS"
}
PoljeObveznoZnačenje
typeda"check"
request_iddavaša oznaka zahtjeva (do 64 znaka)
textdatekst za provjeru
contextnekontekstna provjera (izbor između više ispravnih riječi, stil); zadano false
punctuationneprovjera razmaka oko interpunkcije; zadano false
showinfoneduže objašnjenje uz svaku pogrešku (message); zadano false
originalnetrue vraća i izvorni tekst u odgovoru
appnenaziv vašeg sustava

Polja context, punctuation i showinfo uvijek pošaljite izričito: izostavljeno polje znači false, pa bez njih provjera radi bez kontekstnih pravila i interpunkcije, a pogreške dolaze bez objašnjenja. Za punu provjeru, kakvu radi stranica ispravi.me, pošaljite sva tri s vrijednošću true.

Pojedinačni zahtjev (HTTPS)

curl -s https://ispravi.me/api/ispravi \
  -H 'Content-Type: application/json' \
  -d '{"text": "Ovo je primjerni tekts.", "context": true, "punctuation": true, "showinfo": true, "app": "RedakcijaCMS"}'

Tijelo zahtjeva ima ista polja kao poruka check, bez type i request_id. Prihvaća se i oblik application/x-www-form-urlencoded (vrijednosti true/false ili on/off). Uvijek navedite context, punctuation i showinfo: kod ovog načina izostavljeno polje znači isključeno.

Odgovor je isti kao check_response u nastavku, ali bez polja type, request_id i session_id. HTTP-status odgovora jednak je polju status.code.

Odgovor

{
  "type": "check_response",
  "request_id": "r-1715780000000-a4f2",
  "request": {
    "user": {
      "tier": "guest",
      "tier_name": "Gost",
      "limits": {
        "max_reqs_per_day": 100,
        "reqs_used": 3,
        "reqs_remaining": 97,
        "max_words_per_day": 10000,
        "words_used": 126,
        "words_remaining": 9874,
        "reset_in": 41520,
        "max_words_per_month": 60000,
        "words_used_month": 1830,
        "words_remaining_month": 58170,
        "month_reset_in": 1683120,
        "min_letters": 3
      }
    },
    "text": { "length": 40, "words": 6, "sentences": 1 }
  },
  "response": {
    "errors": 1,
    "error": [
      {
        "id": "T_TYPO",
        "class": "spelling",
        "header": "Zatipak",
        "message": "Ne prepoznajem riječ — vjerojatno je u pitanju zatipak.",
        "suspicious": "tekts",
        "suggestions": ["tekst", "tests"],
        "position": [16],
        "occurrences": 1,
        "length": 5
      }
    ]
  },
  "status": { "code": 200, "text": "OK" }
}

(Primjer je skraćen; odgovor sadrži i podatke o inačici, rečenicama i trajanju obrade.)

U request.user.limits stanje je nakon ove provjere: gost je danas poslao tri provjere s ukupno 126 riječi. reset_in i month_reset_in broj su sekundi do obnove dnevnog, odnosno mjesečnog ograničenja. Mjesečno ograničenje riječi (*_month) imaju samo gosti; kod neograničene vrijednosti umjesto broja stoji null. Na mreži organizacije s Poslovnim planom odgovor sadrži i request.user.org sa zajedničkim ograničenjem organizacije.

Svaka stavka u response.error:

PoljeZnačenje
suspicioustočan dio teksta koji je pogrešan
positionpoložaj svake pojave te pogreške: broj znakova od početka teksta (od 0)
lengthduljina pogrešnog dijela u znakovima
suggestionsprijedlozi ispravka, najbolji prvi; može biti prazno
classvrsta pogreške (vidi ispod)
headerkratki naslov pogreške na hrvatskom
messageduže objašnjenje; može sadržavati <b> i <br />
idoznaka pravila, korisna za povratnu informaciju

Ista pogrešna riječ koja se u tekstu pojavljuje više puta dolazi kao jedna stavka s više položaja u polju position. Položaji se broje u znakovima, ne u bajtovima.

Vrste pogrešaka (class) i kako ih prikazuje stranica ispravi.me:

classPrikaz na ispravi.me
spelling, case-mix, numeric, orthography i sve ostale (npr. major, minor)pravopis (valovita crvena crta)
grammargramatika (puna narančasta crta)
style, pleonasm, punctuation, ambiguous, infostil i napomene (isprekidana plava crta)

Povratna informacija o ispravcima

Kad korisnik prihvati prijedlog ili sam ispravi riječ, javite nam to. Provjera se ne ponavlja; podatak nam služi za poboljšanje prijedloga.

{
  "type": "correction",
  "request_id": "fb-1715780100000-b3c1",
  "error": "tekts",
  "corrected": "tekst",
  "suggestionIndex": 0,
  "errorId": "T_TYPO",
  "xRequestID": "r-1715780000000-a4f2"
}

Kod pojedinačnih zahtjeva ista polja (bez type i request_id) šaljete na POST https://ispravi.me/api/acceptUserInput.

Kodovi pogrešaka

Kod stalne veze pogreška stiže kao poruka {"type": "error", "code": …, "reason": …}, a kod pojedinačnog zahtjeva kao HTTP-status.

KodZnačenjeŠto učiniti
400neispravan zahtjev (JSON, vrsta polja, request_id)ispraviti zahtjev; ne ponavljati
402ograničen pristup: mreža vaše organizacije blokirana je za tekstove dulje od 50 slova (reason: restricted)javiti nam se
406tekst je prekratak: manje od limits.min_letters (tri) slovane slati
413tekst je dulji od 350 000 znakova ili je poruka veća od 768 kB (reason: too_long ili too_large)podijeliti tekst na dijelove
429potrošeno ograničenje ili previše zahtjeva: polje reason kaže koje — vaše (rate_minute, rate_day, rate_month), zajedničko ograničenje vaše organizacije (org_rate_minute, org_rate_day, org_rate_month) ili previše istodobnih zahtjeva. Dok je dnevno ili mjesečno ograničenje potrošeno, tekstovi do 50 slova i dalje prolaze, najviše deset dnevno (limits.grace)pričekati retry_after sekundi i ponoviti
500pogreška na poslužiteljuponoviti kasnije
503poslužitelj je trenutačno zauzetponoviti nakon kratke stanke

Primjer klijenta (JavaScript)

const ws = new WebSocket('wss://ispravi.me/ispravi');
const pending = new Map();

ws.addEventListener('message', (event) => {
    const msg = JSON.parse(event.data);
    if (msg.type === 'session_init') return;          // razina i ograničenja: msg.user
    const request = pending.get(msg.request_id);
    if (!request) return;
    pending.delete(msg.request_id);
    if (msg.type === 'error') request.reject(Object.assign(new Error(msg.reason), { code: msg.code }));
    else request.resolve(msg);
});

function check(text) {
    const request_id = 'r-' + Date.now() + '-' + Math.random().toString(36).slice(2, 7);
    return new Promise((resolve, reject) => {
        pending.set(request_id, { resolve, reject });
        ws.send(JSON.stringify({
            type: 'check', request_id, text,
            context: true, punctuation: true, showinfo: true, app: 'MojSustav',
        }));
    });
}

// Nakon što se veza otvori:
const result = await check('Ovo je primjerni tekts za provjeravanje.');
for (const error of result.response.error) {
    for (const position of error.position) {
        console.log(position, error.suspicious, '→', error.suggestions.join(', '));
    }
}

Prijelaz sa starog sučelja

Ako koristite staro sučelje (POST https://ispravi.me/api/ispravi s parametrom app kao ključem):

  • adresa /api/ispravi ostaje ista i prima iste parametre, a odgovor stiže znatno brže nego prije;
  • parametar app više nije ključ. Možete ga zadržati kao naziv svojeg sustava;
  • vrijednosti on/off i dalje se prihvaćaju, kao i true/false u obliku JSON;
  • osnovna struktura odgovora (request, response.error, status) ostala je ista, ali su dodana nova polja (npr. oznaka pravila id, stanje ograničenja u request.user.limits, granice rečenica) i nove vrijednosti polja class (grammar, style, orthography …). Neka vaš sustav nepoznata polja i vrijednosti zanemaruje, a ne odbacuje odgovor.

Pitanja i prijedloge šaljite na ispravi@ispravi.me.