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) | |
|---|---|---|
| Adresa | wss://ispravi.me/ispravi | https://ispravi.me/api/ispravi (metoda POST) |
| Veza | jedna veza, mnogo provjera | jedan zahtjev, jedna provjera |
| Pogodno za | uređivače u kojima autor piše i često provjerava | povremene provjere, npr. prije objave |
| Povratna informacija | poruka correction kroz istu vezu | POST 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 irequest.user.org). Neograničena vrijednost imanullumjesto 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žiresponse.grammars"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)
- Otvorite vezu prema
wss://ispravi.me/ispravi. - Poslužitelj odmah šalje poruku
session_inits razinom korištenja i ograničenjima. - Šaljete poruke
check, jednu ili više njih zaredom. - Na svaku dobivate
check_response. Odgovori mogu stići drugim redoslijedom, pa ih povezujete prema poljurequest_id, koje sami zadajete i koje se vraća nepromijenjeno. - 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"
}
| Polje | Obvezno | Značenje |
|---|---|---|
type | da | "check" |
request_id | da | vaša oznaka zahtjeva (do 64 znaka) |
text | da | tekst za provjeru |
context | ne | kontekstna provjera (izbor između više ispravnih riječi, stil); zadano false |
punctuation | ne | provjera razmaka oko interpunkcije; zadano false |
showinfo | ne | duže objašnjenje uz svaku pogrešku (message); zadano false |
original | ne | true vraća i izvorni tekst u odgovoru |
app | ne | naziv 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:
| Polje | Značenje |
|---|---|
suspicious | točan dio teksta koji je pogrešan |
position | položaj svake pojave te pogreške: broj znakova od početka teksta (od 0) |
length | duljina pogrešnog dijela u znakovima |
suggestions | prijedlozi ispravka, najbolji prvi; može biti prazno |
class | vrsta pogreške (vidi ispod) |
header | kratki naslov pogreške na hrvatskom |
message | duže objašnjenje; može sadržavati <b> i <br /> |
id | oznaka 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:
class | Prikaz na ispravi.me |
|---|---|
spelling, case-mix, numeric, orthography i sve ostale (npr. major, minor) | pravopis (valovita crvena crta) |
grammar | gramatika (puna narančasta crta) |
style, pleonasm, punctuation, ambiguous, info | stil 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.
| Kod | Značenje | Što učiniti |
|---|---|---|
| 400 | neispravan zahtjev (JSON, vrsta polja, request_id) | ispraviti zahtjev; ne ponavljati |
| 402 | ograničen pristup: mreža vaše organizacije blokirana je za tekstove dulje od 50 slova (reason: restricted) | javiti nam se |
| 406 | tekst je prekratak: manje od limits.min_letters (tri) slova | ne slati |
| 413 | tekst je dulji od 350 000 znakova ili je poruka veća od 768 kB (reason: too_long ili too_large) | podijeliti tekst na dijelove |
| 429 | potroš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 |
| 500 | pogreška na poslužitelju | ponoviti kasnije |
| 503 | poslužitelj je trenutačno zauzet | ponoviti 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/ispraviostaje ista i prima iste parametre, a odgovor stiže znatno brže nego prije; - parametar
appviše nije ključ. Možete ga zadržati kao naziv svojeg sustava; - vrijednosti
on/offi dalje se prihvaćaju, kao itrue/falseu obliku JSON; - osnovna struktura odgovora (
request,response.error,status) ostala je ista, ali su dodana nova polja (npr. oznaka pravilaid, stanje ograničenja urequest.user.limits, granice rečenica) i nove vrijednosti poljaclass(grammar,style,orthography…). Neka vaš sustav nepoznata polja i vrijednosti zanemaruje, a ne odbacuje odgovor.
Pitanja i prijedloge šaljite na ispravi@ispravi.me.