Näin Optiforan API toimii
Tämä sivu kuvaa API:n muodon: miten henkilöllisyys todistetaan, miten versiot etenevät, minkä rajojen sisällä pyyntö pysyy, miltä virhe näyttää ja miten tietoa vaihdetaan ulkomaailman kanssa.
Tuote on kehitysvaiheessa ja API-pinta on yhä täydentymässä. Päätepisteiden referenssiasiakirja julkaistaan erikseen; tällä sivulla ei ole osoitetta eikä esimerkkikutsua, vain toimintaperiaate.
Tunnistautuminen
Jokainen pyyntö kuuluu joko henkilölle tai rekisteröidylle sovellukselle. Ilman henkilöllisyyttä suojattuun päätepisteeseen saapuva pyyntö palautuu tunnistautumattomana.
- Bearer-polettiKäyttöoikeuspoletti kulkee pyynnön authorization-otsakkeessa. Se on allekirjoitettu ja kertoo vain sen, kenelle pyyntö kuuluu.
- Lyhyt elinikäKäyttöoikeuspoletti vanhenee minuuteissa mitattavan ajan kuluttua; pituus on käyttöönoton asetus ja oletuksena kolmekymmentä minuuttia.
- Uudistus ja kierrätysIstuntoa jatketaan uudistuspoletilla, ja jokainen jatko antaa uuden parin. Jos käytetty uudistuspoletti esitetään toisen kerran, kaikki kyseisen henkilön istunnot mitätöidään.
- Käyttöoikeuksia ei leivota polettiinPoletti kantaa vain henkilöllisyyden; se, mitä henkilö saa nähdä, kysytään tietokannalta jokaisella pyynnöllä. Peruttu oikeus lakkaa siis toimimasta jo ennen kuin kädessä oleva poletti vanhenee.
- Integraattorin avainRekisteröity sovellus yhdistää omalla avaimellaan. Selkokielinen arvo näytetään kerran, luontihetkellä; tallennettuna on sen tiiviste ja salaamaton etuliite, jonka avulla avain tunnistetaan.
- Organisaatio myöntää pääsynOlipa sovellus kuinka laajasti käytössä tahansa, ilman organisaation kirjaamaa lupaa se ei näe yhtäkään riviä. Lupa on päivätty, rajattu ja peruutettavissa.
Versiointi
- Versio on polussaPäätepisteet julkaistaan versioetuliitteen takana; tämänhetkinen pinta on versio yksi.
- Rikkova muutos avaa uuden polunOlemassa olevan päätepisteen sopimusta ei rikota paikallaan. Yhteensopimaton muutos julkaistaan uudella versiopolulla, kun vanha jatkaa toimintaansa.
- Asiakirja kertoo oman versionsaReferenssi kantaa sen versionumeron, josta se on tuotettu; asiakirja itse vastaa siihen, mitä versiota luette.
Ympäristöt ja rajat
Referenssi ilmoittaa kaksi ympäristöä: tuotannon ja paikallisen kehityksen. Juuriosoite annetaan integraattorille avaimen mukana; sitä ei julkaista tällä sivulla.
- Elossaolo ja valmius mitataan erikseenYksi päätepiste kertoo, että prosessi on käynnissä; toinen lähettää tietokantaan aidon kyselyn ja varmistaa sen tavoitettavuuden. Vain jälkimmäinen ratkaisee, ohjataanko liikennettä.
- Selainten alkuperät on rajattu listaanEri alkuperästä tulevat pyynnöt hyväksytään vain etukäteen ilmoitetuista alkuperistä; niin kauan kuin lista on tyhjä, selaimen eri alkuperästä tuleva pyyntö hylätään.
- Rungon koon rajaPyynnön runko saa olla enintään viisi megatavua. Suuret aineistot kulkevat omana joukkosiirtotyönään, jolla on oma tilatietue, eivät yhtenä pyyntönä.
- Salaisuuksia ei kirjoiteta lokiinPalvelimen lokiin ei jää authorization-otsaketta, evästettä, salasanaa eikä henkilötunnusta.
Nopeusraja
Raja on osoite- ja minuuttikohtainen. Oletus on 120 pyyntöä minuutissa, ja se asetetaan käyttöönotossa. Jäljellä oleva kiintiö raportoidaan otsakkeissa jokaisessa vastauksessa.
| Vastauksen otsake | Mitä se kertoo |
|---|---|
| x-ratelimit-limit | Aikaikkunan sisäinen kokonaiskiintiö. |
| x-ratelimit-remaining | Mitä tästä aikaikkunasta on jäljellä. |
| x-ratelimit-reset | Sekunnit siihen, kun kiintiö uusiutuu. |
| retry-after | Kuinka monta sekuntia ennen uutta yritystä. Mukana vain siinä vastauksessa, joka hylkäsi pyynnön. |
Kun raja ylittyy, pyyntö hylätään ja vastaus kertoo sekunteina, kuinka kauan on odotettava. Uusi yritys tehdään vasta sen ajan jälkeen, ei heti.
Virheen muoto
Jokainen virhe palaa samassa kuoressa: lyhyt koodikenttä koneen haarautumista varten ja selitekenttä ihmisen luettavaksi.
- errorLyhyt koodi, jonka perusteella asiakas päättää.
- messageSelitys siitä, mitä tapahtui.
| Tila | Koodikenttä | Mitä se tarkoittaa |
|---|---|---|
| 400 | Bad Request | Pyyntö ei vastaa skeemaa. Selite nimeää puuttuvan tai virheellisen kentän. |
| 401 | unauthenticated | Kelvollista henkilöllisyyttä ei ole: polettia ei lähetetty, se on vanhentunut tai sen todennus ei mennyt läpi. |
| 404 | Not Found | Päätepistettä ei ole tai tietuetta ei ole. |
| 429 | Too Many Requests | Nopeusraja ylittyi; vastaus kertoo, kuinka kauan on odotettava. |
| 5xx | internal_error | Odottamaton häiriö. Yksityiskohtaa ei anneta asiakkaalle; se kirjataan palvelimen lokiin. |
Sivutus
Listoja palauttavat päätepisteet ottavat samat kaksi parametria ja palauttavat samat laskurit, joten sivuttavaa asiakasta ei kirjoiteta uudelleen jokaista päätepistettä varten.
- limitKuinka monta tietuetta sivulle mahtuu. Vähintään yksi, enintään kaksisataa; viisikymmentä, jos arvoa ei aseteta.
- offsetKuinka monta tietuetta ohitetaan. Alkaa nollasta.
- totalKuinka moni tietue vastaa suodattimia yhteensä.
- countKuinka monta tietuetta tämä vastaus tosiasiassa kantaa.
Vastaus toistaa myös käyttämänsä limit- ja offset-arvot; asiakas lukee sijaintinsa vastauksesta sen sijaan, että arvaisi sen.
Tiedonvaihto ja webhookit
Vaihdon tapa on asetus, ei erillinen tuote: jokainen rekisteröity sovellus kantaa omassa tietueessaan sen tavan, jolla se toimii.
| Tapa | Mitä se tarkoittaa |
|---|---|
| Yksisuuntainen — ulos | Optifora julkaisee tiedon; vastapuoli lukee sen tai tilaa tapahtumat. |
| Yksisuuntainen — sisään | Vastapuoli työntää tiedon; Optifora tarkistaa sen ja kirjoittaa sen. |
| Kaksisuuntainen | Molemmat osapuolet kirjoittavat; ristiriitasääntö on määritelty etukäteen. |
| Kättely | Jokainen siirto avaa istunnon: tarjous, todennus, hyväksyntä, siirto ja kuitti. Kuitti jää molemmille osapuolille. |
- Tapahtumat työnnetään ulosWebhook lähettää tapahtuman siihen paluuosoitteeseen, jonka rekisteröity sovellus on ilmoittanut. Tapahtuma, jota ei saada perille, jää jonoon ja lähetetään uudelleen; sitä ei koskaan hiljaisesti hylätä.
- Sama pyyntö ei kirjoita kahdestiKirjoituspyyntö kantaa idempotenssiavaimen. Toinen samalla avaimella tehty pyyntö ei luo toista tietuetta.
- Jokainen kutsu mitataanKuka kutsui, milloin, millä laajuudella ja millä tuloksella — kaikki kirjataan. Sama kirjaus vastaa sekä vianetsintään että kysymykseen siitä, kuka tämän tiedon haki.
- Omat sovelluksemme käyttävät samaa oveaEtuoikeutettua toista reittiä ei ole. Oma integraatiomme on todiste siitä pinnasta, jonka ulkopuolinen kehittäjä kohtaa.
Vaihtokerroksen tietomalli on valmis; sen päätepisteitä ei ole vielä julkaistu. Kun ne julkaistaan, tämä osio linkittää niiden kohtiin referenssissä.
Referenssiasiakirjat
Referenssiä ei kirjoiteta käsin; se tuotetaan päätepisteiden skeemoista. Kun kukin päätepiste luovuttaa skeemansa, asiakirja täydentyy itsestään, joten asiakirja ja toiminta eivät voi erkaantua toisistaan.
- Tänään: valmisteillaSkeemat valmistuvat moduuli kerrallaan. Ennen asiakirjan julkaisua jokaisen päätepisteen pyyntö ja vastaus näkyvät siinä.
- Julkaistaan kahdessa muodossaKoneluettava OpenAPI-asiakirja sekä samasta asiakirjasta tuotettu, selaimessa selattava referenssisivu.
- Pääsy on porrastettuYleiskatsaus on avoin kaikille. Täysi referenssi voi olla rekisteröidylle integraattorille annetun dokumentaatiopoletin takana; tuotantoavaimet ja paluuosoitteet eivät kuulu dokumentaatioon lainkaan — ne kuuluvat sovelluksen tietueeseen.
- OsoitestandardiJulkaistavia referenssejä on kaksi ja niiden osoitteet ovat kiinteät: client-api.optifora.com/docs on avoin, admin-api.optifora.com/docs vaatii valtuutuksen ja on suljettu ulkopuolisilta. Kumpikaan ei ole vielä toiminnassa; linkit lisätään tähän kohtaan, kun ne ovat.
Jos integraatiosuunnitelmanne on jo selvä, kirjoittakaa meille yhteydenottosivulta: kuulette ensimmäisten joukossa, kun pinta avataan.
Onko teillä tietty pyyntö?
Nämä sivut selittävät, miten tukiprosessi toimii. Jos teillä on pyyntö tai kysymys, kirjoittakaa meille yhteydenottosivulta.
Siirry yhteydenottosivulle