REST-gränssnitt
Inledning
ServITs Rest API erbjuder möjligheten att läsa, skapa/uppdatera eller ta bort resurser i er miljö i vårt system.
Nedan beskrivs ServITs api som är rest-baserat. Först beskrivs autentisering, versionshantering och hur url-länken är uppbyggd, sedan kommer ett avsnittet indelat per resurs och beskrivning av vilka verb och länkar som fungerar med respektive resurs.
Autentisering
I rubriken till html-anropet anges följande, Authorization: Basic base64(username:password), där username och password krypteras med bas 64, separerat med ett kolon. Username är det användarnamn ni har i systemet och password är det lösenord ni använder. Exempel: Authorization: Basic RUhETFFIFzpUFFdWSehDTQ==
Verb
I ett html-anrop så finns det html verb som skickas med. De verben som används är följande.
| Verb | Beskrivning |
|---|---|
| GET | Hämtar/läser en resurs |
| POST | Skapar/Uppdaterar en resurs |
| DELETE | Tar bort en resurs. |
Avvikelser verb
POST vs PUT Vi använder POST för vid både updatering av en befintlig post och vid skapade av en post, svs, PUT utgår som verb i vårt API.
Länk
Apiet nås via https:///RestAPI/....
Uppbyggnad av URL-länken
.../version/resurs1[/id1]...[/resursX][/idX]?info_type=value¶m1=value1...¶mY=valueY
| Del i länk | Beskrivning |
|---|---|
| Version | Versionsid som anger version av api |
| Resurs | Resurs som skall bearbetas |
| Id | Id som pekar ut en resurs |
| Info_type | Eventuell information som önskat om resursen |
| Param | Parameter/Parametrar som kan beskriva ett önskat urval eller filtrering |
Returkoder
Rest använder de returkoder som redan finns I html. De vanligaste koderna är enligt nedan.
| Returkod | Beskrivning |
|---|---|
| 200 | Förfrågan gick bra. |
| 201 | En resurs skapades eller uppdaterades. Används vid metoderna PUT och POST. |
| 204 | Förfrågan gick bra. Ingen data returneras. |
| 400 | Fel format på förfrågan. Används valigen vid metoderna PUT och POST. |
| 401 | Det gick inte att säkerställa vem som ställt frågan. |
| 404 | Efterfrågad resurs gick inte att hitta. |
| 405 | Metoden I frågan används ej av apiet. |
| 409 | Exempelvis, resursen finns redan vid försök att skapa den. |
| 500 | Övriga fel. |
Parametrar
API
Följande parametrar är giltiga i api't.
| Parameter | Beskrivning | Min. | Max | Giltiga värden | Default | Exempel |
|---|---|---|---|---|---|---|
| sort | Styr sorteringen på lista med resurser. | asc, desc | ||||
| limit | Begränsar antal svar vid flera resurser. | 1 | 1000 | 1000 | ||
| id_in | En lista med giltiga resurser för att begränsa urval. | id_in=1,2,3 | ||||
| info_type | Ger information om en resurser. | stat, status | ||||
| count | Returnerar antal poster. | count=1 |
Sökning
För sökning efter en eller flera resurser kan datafält anges som parameter i url-strängen.
Det går att söka på varje fält som returneras i returdatan för en resurs enligt '...\{id}?datafält={value}'.
Exempelvis, '.../users?usermail=namn@adress.se', söker efter användare med e-postadressen 'namn@adress.se'.
Urval
För sökning efter ett urval av resurser kan ett urval anges i url-strängen enligt '...\{id}?datafält:{operator}={value}'.
Exempelvis, '.../users?addts:gt=20200825', söker efter användare som lades till efter 20200825.
För att ange ett spann anges datafältet 2 gånger med 2 olika operatörer enligt '...\{id}?datafält:{operator}={value}&datafält:{operator}={value}'.
Följande operatörer finns.
| Operator | Anges som | Beskrivning | Exempel |
|---|---|---|---|
| < | lt | Mindre än | addts:lt=20200825 |
| <= | le | Mindre än eller lika med | addts:le=20200825 |
| >= | ge | Större än eller lika med | addts:ge=20200825 |
| > | gt | Större än | addts:gt=20200825 |
Resurser
Generella resurser
Generella resurser för generella REST-api.
| Beskrivning | Resurs | Giltiga metoder | Möjlig information |
|---|---|---|---|
| B-nummer | bnos | GET | |
| Samtal | calls | GET | |
| Företag | companies | GET | pbx_stat |
| Kontakter | contacts | GET | |
| Telefonnummer för kontakt | crm_aid | GET | |
| Extra e-post för kontakt | crm_contactmail | GET | |
| Sökord för kontakt | crm_contactsearch | GET | |
| Status för kontakt | crm_contactstatus | GET | |
| Ärende logg | crm_logs | GET | |
| Mallar | crm_template | GET | |
| Svarsställe | sites | GET | pbx_stat, stat, status |
| Tips för kontakt/företag | pbxtips | GET | |
| Ärenden | tickets | GET | |
| Köer | queues | GET | calls, call_status, status |
| Användare | users | GET | status |
| Händelselogg för användare | userlogs | GET | |
| Handläggarstatistik | userstats | GET | |
| Svarsgruppstatistik | teamstats | GET |