API-FIRST / RESTFUL API / OPENAPI

API sučelje za Service Desk / Incident Management

Dokumentacija RESTful API sučelja izlaže kompletne web servise rješenja za upravljanje IT uslugama: tikete, incidente, servisne zahtjeve, korisnike, grupe, imovinu, konfiguracijske stavke, bazu znanja, katalog usluga, SLA pravila, integracije, webhooks, izvještaje i administraciju sustava.

4.1 Općenito REST endpointi Strukture podataka Integracije Sigurnost OpenAPI primjer

Osnovni princip

API-first. Svi ključni entiteti i funkcije sustava dostupni su programskim putem kroz dokumentirano, sigurno i robusno REST API sučelje.

Format. JSON preko HTTPS protokola, uz OpenAPI/Swagger dokumentaciju, autorizaciju, audit zapise i primjere poziva.

Pogledaj web servise

4.1. Opći zahtjevi za povezivanje

01

API-first arhitektura

Rješenje je građeno na API-first principu. To znači da postoji sveobuhvatan, dobro dokumentiran, robustan i siguran RESTful API za programski pristup svim ključnim entitetima i funkcijama sustava.

02

Kompletna dokumentacija

API dokumentacija mora biti dostupna u Swagger/OpenAPI formatu, s opisom endpointa, metoda, parametara, autorizacije, primjera zahtjeva i primjera odgovora za svaki servis.

03

CRUD za ključne entitete

API izlaže operacije Create, Read, Update i Delete za tikete, korisnike, imovinu, konfiguracijske stavke, članke baze znanja, katalog usluga i ostale ključne module.

Obuhvat API-ja: API pokriva ITSM i uredske procese sustava, uključujući prijavu i obradu incidenata, servisne zahtjeve, zadatke, promjene, probleme, SLA, CMDB, imovinu, korisnike, grupe, uloge, dokumente, priloge, obavijesti, izvještaje i integracije.

Katalog REST web servisa

Predložena bazna putanja API-ja je /api/v1. Svi servisi koriste HTTPS, JSON payload i standardne HTTP metode.

Modul Metode i endpointi Svrha / izložena funkcionalnost
Autentikacija i sesije POST/auth/token
POST/auth/refresh
POST/auth/logout
GET/auth/me 		Prijava korisnika, izdavanje i osvježavanje tokena, odjava, dohvat trenutno prijavljenog korisnika, MFA status i prava pristupa.
Korisnici, grupe i uloge GET/users
POST/users
GET/users/{id}
PUT/users/{id}
GET/groups, /roles 		Administracija korisnika, tehničara, agenata, grupa podrške, timova, uloga, ovlaštenja, organizacijskih jedinica i korisničkih profila.
Katalog usluga GET/service-catalog
POST/service-catalog
GET/service-catalog/{id}
PUT/service-catalog/{id} 		Definiranje i objava IT usluga, kategorija usluga, obrazaca zahtjeva, odobravanja, SLA pravila i vidljivosti prema korisničkim grupama.
Tiketi GET/tickets
POST/tickets
GET/tickets/{id}
PATCH/tickets/{id}
DELETE/tickets/{id} 		Centralni objekt za incidente, servisne zahtjeve, upite i radne naloge: statusi, prioriteti, kategorije, dodjela, eskalacije, privitci, komentari i historija.
Incident Management GET/incidents
POST/incidents
PATCH/incidents/{id}/assign
PATCH/incidents/{id}/resolve
PATCH/incidents/{id}/reopen 		Prijava, klasifikacija, prioritetizacija, dodjela, rješavanje i zatvaranje incidenata, uključujući vezu na korisnike, imovinu, CI i SLA.
Service Request Management GET/service-requests
POST/service-requests
PATCH/service-requests/{id}/approve
PATCH/service-requests/{id}/fulfill 		Servisni zahtjevi iz kataloga usluga, odobravanja, izvršenje zahtjeva, dodjela zadataka i praćenje realizacije.
Problem Management GET/problems
POST/problems
PATCH/problems/{id}
POST/problems/{id}/known-errors 		Analiza uzroka ponavljajućih incidenata, evidentiranje poznatih grešaka, workarounda i trajnih rješenja.
Change Management GET/changes
POST/changes
PATCH/changes/{id}/approve
PATCH/changes/{id}/schedule
PATCH/changes/{id}/close 		Upravljanje promjenama, odobravanje, planiranje, procjena rizika, povezivanje s CI, imovinom, incidentima i dokumentacijom.
Zadaci i aktivnosti GET/tasks
POST/tasks
PATCH/tasks/{id}
PATCH/tasks/{id}/complete 		Operativni zadaci vezani uz tikete, zahtjeve, promjene, implementaciju, podršku, obuke i interne aktivnosti.
SLA / OLA / UC GET/sla-policies
POST/sla-policies
GET/tickets/{id}/sla
GET/sla-breaches 		Definicija rokova odgovora i rješavanja, radnih kalendara, eskalacija, kršenja SLA i izvještavanja o nivou usluge.
Imovina / Assets GET/assets
POST/assets
GET/assets/{id}
PUT/assets/{id}
GET/assets/{id}/tickets 		Inventar opreme, uređaja, licenci, softvera, zaduženja, statusa, lokacija, korisnika i veza prema incidentima i servisnim zahtjevima.
CMDB / konfiguracijske stavke GET/configuration-items
POST/configuration-items
GET/configuration-items/{id}/relations
POST/configuration-items/{id}/relations 		Konfiguracijske stavke, relacije između sustava, aplikacija, servera, servisa i imovine, utjecaj na incidente i promjene.
Baza znanja GET/knowledge/articles
POST/knowledge/articles
PUT/knowledge/articles/{id}
GET/knowledge/search 		Članci, upute, rješenja, workaroundi, kategorije, odobravanje i javna/interna vidljivost prema korisnicima i agentima.
Prilozi i dokumenti POST/attachments
GET/attachments/{id}
DELETE/attachments/{id}
POST/documents 		Upload slika grešaka, dokumenata, zapisnika, ugovora, računa i drugih priloga vezanih uz tikete, promjene, imovinu i bazu znanja.
Komentari i komunikacija GET/tickets/{id}/comments
POST/tickets/{id}/comments
POST/tickets/{id}/mentions 		Interni i javni komentari, @mention, komunikacija s korisnikom, agentima i timovima, povezivanje s e-mail i Teams kanalima.
Obavijesti GET/notifications
POST/notifications/send
PUT/notification-templates/{id} 		E-mail, push, Teams i sistemske obavijesti o statusu tiketa, dodjeli, eskalaciji, odobrenju, rješenju i kršenju SLA.
Webhookovi GET/webhooks
POST/webhooks
DELETE/webhooks/{id}
POST/webhooks/{id}/test 		Slanje događaja vanjskim sustavima kod kreiranja, izmjene, zatvaranja ili eskalacije tiketa, promjene CI, novog članka ili promjene korisnika.
Integracije GET/integrations
POST/integrations/ad/sync
POST/integrations/email/import
POST/integrations/siem/events 		Active Directory / Entra ID, Exchange / Office 365, Teams, SIEM, Intune i druge obavezne i dodatne integracije.
Izvještaji i dashboardi GET/reports/tickets
GET/reports/sla
GET/reports/assets
GET/dashboards/{id} 		Operativni i menadžerski izvještaji, SLA pokazatelji, opterećenje agenata, trendovi incidenata, imovina i status usluga.
Audit i sigurnosni zapisi GET/audit-logs
GET/security/events
GET/access-logs 		Sljedivost svih aktivnosti: prijava, izmjena podataka, promjena prava, integracijski pozivi, administrativne akcije i sigurnosni događaji.

Strukture ključnih entiteta

Ticket / Incident objekt

{
  "id": "TCK-2026-000145",
  "type": "incident",
  "title": "Greška u AIS/BIS sistemu",
  "description": "Korisnik ne može pristupiti modulu.",
  "status": "new",
  "priority": "high",
  "impact": "department",
  "urgency": "high",
  "category": "application",
  "serviceId": "SRV-AIS-BIS",
  "requesterId": "USR-10021",
  "assigneeId": "USR-AGENT-04",
  "groupId": "GRP-L2-APPLICATIONS",
  "assetIds": ["AST-45001"],
  "configurationItemIds": ["CI-AIS-APP-01"],
  "sla": {
    "responseDueAt": "2026-05-12T10:30:00Z",
    "resolutionDueAt": "2026-05-12T16:30:00Z",
    "breached": false
  },
  "attachments": [],
  "createdAt": "2026-05-12T10:10:00Z",
  "updatedAt": "2026-05-12T10:12:00Z"
}

Asset / imovina objekt

{
  "id": "AST-45001",
  "assetTag": "ZZOKS-LAP-0021",
  "name": "Laptop ordinacija 21",
  "type": "laptop",
  "manufacturer": "Dell",
  "model": "Latitude",
  "serialNumber": "ABC123456",
  "status": "in_use",
  "assignedTo": "USR-10021",
  "location": "Ambulanta Sarajevo",
  "warrantyExpiresAt": "2028-03-01",
  "linkedConfigurationItems": ["CI-AIS-APP-01"],
  "createdAt": "2026-01-15T09:00:00Z"
}

Configuration Item / CI objekt

{
  "id": "CI-AIS-APP-01",
  "name": "AIS/BIS aplikativni servis",
  "ciType": "application_service",
  "status": "operational",
  "environment": "production",
  "ownerGroupId": "GRP-L2-APPLICATIONS",
  "criticality": "high",
  "relations": [
    {
      "targetCiId": "CI-DB-01",
      "relationshipType": "depends_on"
    }
  ],
  "linkedServices": ["SRV-AIS-BIS"]
}

Knowledge Article objekt

{
  "id": "KB-00089",
  "title": "Postupak kod greške prijave u AIS/BIS",
  "summary": "Upute za provjeru korisničke sesije i SSO prijave.",
  "content": "Koraci za agenta...",
  "category": "AIS/BIS",
  "visibility": "agents_and_users",
  "status": "published",
  "tags": ["AIS", "BIS", "SSO", "login"],
  "relatedTicketIds": ["TCK-2026-000145"],
  "approvedBy": "USR-MANAGER-01",
  "publishedAt": "2026-05-13T08:00:00Z"
}

Standardni parametri za listanje i pretragu

ParametarPrimjerOpis
page, pageSize?page=1&pageSize=50Straničenje rezultata.
sort?sort=-createdAtSortiranje po datumu, prioritetu, statusu ili drugom polju.
filter?status=open&priority=highFiltriranje po statusu, prioritetu, tipu, korisniku, grupi ili usluzi.
query?query=AIS%20greškaPuna tekstualna pretraga po naslovu, opisu i komentarima.
include?include=comments,attachments,slaUključivanje povezanih objekata u odgovoru.

Standardna struktura odgovora

{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 1250,
    "totalPages": 25
  },
  "traceId": "req-7f3a9f2c"
}

Standardna struktura greške

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Obavezno polje title nije popunjeno.",
    "details": [
      {
        "field": "title",
        "issue": "required"
      }
    ]
  },
  "traceId": "req-9b11c8e4"
}

Obavezne i podržane integracije

API sloj mora omogućiti integraciju s postojećim ekosistemom korisnika i standardnim industrijskim platformama.

Sistem za integraciju Smjer Tehnologija Svrha i ključni podaci za razmjenu
Microsoft Active Directory / Azure Active Directory / Entra ID Jednosmjerna prema ITSM LDAP / Graph API Sinkronizacija korisnika, grupa i organizacijskih jedinica, jedinstven izvor identiteta, SSO prijava korisnika i agenata.
Microsoft Exchange / Office 365 Dvosmjerna EWS / Graph API Automatsko kreiranje i ažuriranje tiketa iz e-mail poruka, slanje notifikacija, ažuriranje tiketa odgovorom na e-mail.
Microsoft Teams Dvosmjerna Graph API / Bots Kreiranje tiketa iz Teams chata ili kanala, notifikacije o statusu, pokretanje chata s korisnikom, bot za jednostavne upite.
SIEM, npr. IBM QRadar Jednosmjerna prema ITSM REST API / Webhook / E-mail Automatsko kreiranje sigurnosnih incidenata iz korelacijskih pravila, prioriteti, opis, izvorne IP adrese, pogođeni korisnici i link prema SIEM događaju.
Microsoft Intune / Endpoint Management Dvosmjerna Graph API Prikaz compliance statusa uređaja, sigurnosnih politika, te pokretanje akcija kao Sync, Restart ili Scan direktno iz ITSM sučelja.
ERP / financijski sustavi Dvosmjerna REST API / Webhook Povezivanje ugovora, računa, dobavljača, troškova, licenci i servisnih aktivnosti s poslovnim sustavima.
HR sustavi Jednosmjerna ili dvosmjerna REST API / CSV / LDAP Sinkronizacija zaposlenika, organizacijskih jedinica, radnih mjesta, dostupnosti i kontakt podataka.

Sigurnost, kontrola pristupa i usklađenost

Autentikacija

API podržava OAuth2 / OpenID Connect, JWT access tokene, refresh tokene, servisne API ključeve i SSO integraciju s identitetskim providerima.

Autorizacija

Role-Based Access Control (RBAC) omogućava granularna prava za pregled, kreiranje, izmjenu, brisanje i administraciju podataka po modulima.

Audit trail

Svaki API poziv bilježi korisnika ili servisni račun, vrijeme, endpoint, IP adresu, rezultat, traceId i promijenjena polja.

Enkripcija

Komunikacija se obavlja isključivo preko HTTPS/TLS 1.2+ protokola, a podaci u mirovanju se štite jakom enkripcijom.

Rate limiting

API podržava ograničenje broja poziva po korisniku, IP adresi ili integracijskom klijentu radi zaštite dostupnosti sustava.

GDPR i sigurnosni standardi

Sustav podržava zahtjeve zaštite ličnih podataka, sigurnosne kontrole, logiranje pristupa i usklađenost s relevantnim certifikacijama.

HTTP status kodovi

StatusZnačenjePrimjena
200 OKUspješan zahtjevDohvat ili izmjena resursa.
201 CreatedKreiran resursKreiranje tiketa, korisnika, članka, asseta ili CI.
400 Bad RequestNeispravan zahtjevValidacijska greška ili neispravan payload.
401 UnauthorizedNema autentikacijeNedostaje ili je istekao token.
403 ForbiddenNema ovlaštenjaKorisnik nema pravo za traženu akciju.
404 Not FoundResurs ne postojiNepostojeći ticket, korisnik, CI ili asset.
409 ConflictKonflikt stanjaPokušaj zatvaranja već zatvorenog tiketa ili konflikt verzije.
429 Too Many RequestsPreviše pozivaRate limit je prekoračen.
500 Internal Server ErrorSistemska greškaNeočekivana greška, uz obavezni traceId.

OpenAPI / Swagger struktura

Javno dostupna API dokumentacija može biti objavljena na putanji /api/docs, dok se OpenAPI JSON može izložiti na /api/openapi.json.

openapi: 3.0.3
info:
  title: Service Desk / ITSM REST API
  version: "1.0.0"
servers:
  - url: https://itsm.example.ba/api/v1
security:
  - bearerAuth: []
paths:
  /tickets:
    get:
      summary: Dohvat liste tiketa
      parameters:
        - name: status
          in: query
          schema:
            type: string
        - name: priority
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Lista tiketa
    post:
      summary: Kreiranje novog tiketa
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TicketCreateRequest"
      responses:
        "201":
          description: Ticket kreiran
  /tickets/{id}:
    get:
      summary: Dohvat pojedinačnog tiketa
    patch:
      summary: Izmjena tiketa
    delete:
      summary: Brisanje ili deaktivacija tiketa
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    TicketCreateRequest:
      type: object
      required: [type, title, description, requesterId]
      properties:
        type:
          type: string
          enum: [incident, service_request, question, task]
        title:
          type: string
        description:
          type: string
        requesterId:
          type: string
        priority:
          type: string
          enum: [low, medium, high, critical]

Primjer kreiranja incidenta

POST /api/v1/incidents
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "title": "Greška u AIS/BIS sistemu",
  "description": "Doktor ne može otvoriti karton pacijenta.",
  "requesterId": "USR-10021",
  "priority": "high",
  "category": "application",
  "serviceId": "SRV-AIS-BIS",
  "attachments": [
    {
      "attachmentId": "ATT-77812"
    }
  ]
}

Primjer webhook događaja

{
  "event": "ticket.created",
  "eventId": "EVT-2026-000001",
  "occurredAt": "2026-05-12T10:10:00Z",
  "data": {
    "ticketId": "TCK-2026-000145",
    "type": "incident",
    "priority": "high",
    "status": "new",
    "serviceId": "SRV-AIS-BIS"
  },
  "signature": "sha256=..."
}

Zaključak

Ova stranica definira API sučelje kao sastavni dio ITSM rješenja. REST API izlaže sve ključne module i entitete, omogućava integraciju s postojećim sistemima, podržava standardnu OpenAPI dokumentaciju i osigurava programsku dostupnost funkcionalnosti koje su potrebne za implementaciju Service Desk / Incident Management rješenja.

Povratak na Office Productivity Suite