Začetek z API-jem

Uvod

Dobrodošli v mDocs+ API dokumentacijo! Ta odsek vas bo vodil skozi začetne korake, potrebne za uporabo našega API-ja.

Predpogoji

Preden začnete, poskrbite, da imate naslednje:

• Aktiven račun: Če še niste, poskrbite, da je bil za vas ustvarjen račun.
• API ključ: Vaš API ključ lahko najdete na profilu pod zavihkom API.

HTTP zaglavja (headers)

Izboljšajte svojo interakcijo z API-jem z uporabo posebnih funkcij, ki so na voljo na določenih končnih točkah. Do teh funkcij lahko dostopate z dodajanjem parametrov v zaglavje zahteve.

Zaglavja (Headers)

Polje	Tip	Opis	Privzeta vrednost	Obvezno
Authorization	Bearer Token	Žeton za avtentikacijo		✔️
expand	string	Razširjena polja
fields	string	Polja, ki jih vrne zahtevek
href	boolean	(true|false) Vrne URL od posameznega dokumenta	false
dateFormat	string	Format datuma za časovna polja	php:d.m.Y H:i:s
dateFields	string	Polja, za katera se uporabi oblika datuma nastavljenega z dateFormat
ignoreMissingReference	boolean	(true|false) Uporabljeno pri referenčnem nastavljanju polj	false
ignoreDuplicateReference	boolean	(true|false) Uporabljeno pri referenčnem nastavljanju polj	true

Primer

{
  "Authorization": "xfWuluzj...",
  "expand": "documentType.*,createdBy.name",
  "fields": "id,subject",
  "href": "true",
  "dateFormat": "php:d/m/Y",
  "dateFields": "created_at,updated_at",
  "ignoreMissingReference": "true",
  "ignoreDuplicateReference": "false"
}

Authorization

Zaglavje "Authorization" je ključna komponenta za varovanje dostopa do strežniških virov, saj služi kot ključ za overjanje uporabnikov ali aplikacij, ki pošiljajo zahteve. Mora biti vključeno v vsako API zahtevo, ker zagotavlja, da je dostop dovoljen le pooblaščenim osebam.

API_KEY ključ najdete na vašem profilu, pod zavihkom API.

Fields

Zaglavje "Fields" omogoča selektivno pridobivanje podatkov, ko v zaglavje navedete željena polja, strežnik vključi samo navedena polja. Funkcionalnost omogoča, da prejmete le informacije, ki jih potrebujete, kar optimizira prenos podatkov in poenostavi obdelavo odgovora.

Z navedbo id, created_at in created_by v parametru "fields", se zahteva prilagodi tako, da odgovori samo s temi bistvenimi informacijami.

{
  "id": 5,
  "created_at": "14.11.2025 10:11:31",
  "created_by": 13
}

Expand

Zaglavje "Expand" je funkcionalnost, ki izboljša iskanje podatkov, saj omogoča vključitev podrobnih informacij iz povezanih polj (šifrantov).

Na primer, če podatkovna zbirka hrani referenco, kot je created_by ta običajno kaže na uporabnika (na njegov id). Sama referenca ne zagotavlja zadostnega konteksta. Z uporabo tega zaglavja lahko določite dodatne atribute, kot je npr. createdBy.id, createdBy.username in tako obogatite odgovor z bolj smiselnimi podatki.

Ta funkcija omogoča vključitev imena uporabnika neposredno v odgovor, kar omogoča jasnejše razumevanje izvora dokumenta.

{
  "id": 5,
  "created_at": "14.11.2025 10:11:31"
  "createdBy": {
    "id": 13,
    "username": "superadmin"
  }
}

Href

Zaglavje "Href" je funkcionalnost, ki v odgovor poda URL na dobljeni dokument.

DateFormat

Zaglavje "DateFormat" je funkcionalnost, ki vam omogoča formatiranje datumskih polj. Z določitvijo željene oblike v glavi zahteve lahko zagotovite, da se podatki o datumu in času vrnejo v strukturi, ki vam najbolj ustreza.

Formatiranje

Spodaj so specifikacije formatov, ki jih lahko uporabite z glavo DateFormat, vključno z opisi in primeri:

Privzeta vrednost

• Vzorec formata: php:d.m.Y H:i:s
• Opis: Privzeta vrednost, ki se uporabi v primeru, da dateFormat ni nastavljen.
• Primer: 15.02.2024 12:11:31

ISO 8601 Date and Time

• Vzorec formata: php:Y-m-d\TH:i:s\Z
• Opis: Oblikuje datum in čas v skladu s standardom ISO 8601, ki se pogosto uporablja za internacionalizacijo.
• Primer: 2024-02-15T12:11:31Z

Short Date

• Vzorec formata: php:d/m/Y
• Opis: Zagotavlja jedrnat prikaz datuma brez časa, kar je idealno za preproste prikaze datuma.
• Primer: 15/02/2024

Long Date with Textual Month

• Vzorec formata: php:d F Y
• Opis: Prikaže datum s celotnim imenom meseca, kar omogoča bolj berljivo obliko za aplikacije, osredotočene na vsebino.
• Primer: 15 February 2024

Full DateTime with Day Name

• Vzorec formata: php:l, d F Y H:i:s
• Opis: Vključuje celoten datum in uro z dnevom v tednu, kar zagotavlja izčrpne časovne informacije.
• Primer: Friday, 15 February 2024 12:11:31

DateFields

Zaglavje "dateFields" je funkcionalnost, ki omogoča formatiranje samo določenih polj v formatu, ki je naveden v "dateFormat" zaglavju.

Query parametri

Nekatere GET zahteve omogočajo filtriranje podatkov z dodajanjem parametrov poizvedb na podlagi imen polj.

Če na primer kot parameter poizvedbe uporabite ?country=slovenia, bodo vrnjeni vsi uporabniki iz Slovenije. Lahko tudi povečate natančnost poizvedbe tako, da dodate več parametrov, vendar pa morate za pravilno dodajanje več filtrov namesto ponavljajočega ? uporabiti simbol &.

Na primer, ?country=slovenia&full_name=janez, bo vrnil uporabnike iz "Slovenije" in z imenom "janez".

Poleg filtriranja zahtevka po imenih polj, lahko tudi prilagodite paginacijo: Paginacija je privzeto nastavljena, da vrne prvih 20 rezultatov. Z parametrom page določite katero stran naj API vrne, parameter per-page pa določa koliko rezultatov se prikaže na posamezni strani

Primer: page=2&per-page=5 bo vrnil 5 rezultatov iz druge strani.

Šifranti

Mnogi zapisi imajo kot polje lahko shranjen šifrant iz drugega zapisa.

Polje ki predstavlja šifrant lahko prepoznamo po imenu, in sicer v veliki večini primerov se ime polja zaključi z _id, npr: document_type_id ali pa classification_code_id. Izjema sta polji created_by in updated_by.

Ker tovrstna polja hranijo le referenco (id) do drugega zapisa, si lahko pri pridobivanju podatkov pomagamo z zaglavjem Expand. Pri kreiranju/posodabljanju zapisa pa si lahko pomagamo z referenčnim nastavljanjem polj.

Referenčno nastavljanje polj

Pod referenčnimi polji so vedno shranjeni identifikatorji od povezanih zapisov, zato moramo pri delu s povezanimi polji vedno uporabljati identifikatorje.

Npr. pod povezano polje document_type_id želimo nastaviti sledeč šifrant:

// get document-type/

{
  "id": 2,
  "uuid": "6be1...V98",
  "name": "Certifikat",
  "description": "Certifikat xyz"
},

Če poznamo ID od šifranta ga seveda lahko nastavimo direktno, lahko pa ga nastavimo preko reference s sledečim formatom:

"$ref.[polje]": "[mdocs_model_class];[polje_za_iskanje];[iskan_niz]"

Podatke o [mdocs_model_class] lahko pridobimo z info klicom, opisanem tukaj.

// create document/

{
  "document_type_id": 2
  // ali
  "$ref.document_type_id": "mikrografija.mdocs.document.models.DocumentType;name;certifikat"
  // ali
  "$ref.document_type_id": "mikrografija\\mdocs\\document\\models\\DocumentType;name;certifikat"
},

V zgornjem primeru vsi načini dosežejo enak rezultat. Pri prvem nastavimo polje direktno, pri drugih dveh pa preko reference;

Pri drugem načinu API-ju sporočimo, da želimo ustvariti zapis za document, pri katerem naj bo v polju document_type_id shranjen tisti document-type, ki ima v polju name = 'certifikat'.

Referenčna zaglavja

Pri referenčnem nastavljanju polja lahko uporabimo dva dodatna zaglavja:

ignoreMissingReference

Po privzetem false

V primeru, da document-type ki naj bi imel name = 'certifikat' ne obstaja, API klic ne bo uspešen. Z uporabo zaglavja ignoreMissingReference lahko to napako ignoriramo - polje bo nastavljeno na null

ignoreDuplicateReference

Po privzetem true

V primeru, da imamo dva zapisa, ki imata vrednost name = 'certifikat', se bo uporabilo zapis z večjo identifikacijsko številko (id = 3 pri spodnjem primeru).

Z uporabo zaglavja ignoreDuplicateReference = false, API klic v primeru podvojenih zapisov ne bo uspešen.

// get document-type/

{
  "id": 2,
  "uuid": "6be1...V98",
  "name": "Certifikat",
  "description": "Certifikat xyz"
},
{
  "id": 3,
  "uuid": "asg4...G3D",
  "name": "Certifikat",
  "description": "Certifikat 123"
},