Detta API bygger på Fi2xml version 1.31. XML-representation finns definierad i följande fi2-xsd:er:

XSD Url
fi2base.xsd http://www.fi2.se/schemas/1.31/fi2base.xsd
fi2simplemessage.xsd http://www.fi2.se/schemas/1.31/fi2simplemessage.xsd
fi2fastapi.xsd http://www.fi2.se/schemas/1.31/fastapi/1.1/fi2fastapi.xsd


/api/<entitet>/<id>
Vid GET-anrop till ett specifikt utpekat id returneras alltid endast den entiteten utan omslutande rotnod. Med dessa anrop kan inte ytterligare parametrar skickas med.

/api/<entitet>
När anropets url endast pekar på en entitet returneras resultatet i en omslutande nod, fi2fastapisimplemessage. Det gäller oavsett vilken filtrering som gjorts eller om det är noll, en eller flera element som returneras.



Validering ska göras vid skrivning till API:et. Den validering som krävs av API:et är att det ska vara en korrekt xml, samt valideras korrekt mot xsd:n.
Misslyckas valideringen ska det resultera i ett felmeddelande med felkod 2002 för felaktig input data.

Se nedan för hantering av teckenkodning och fältlängder.

Om det vid skrivning till API:et kommer in felaktiga koder för de befintliga klass-, usage- och värde-listorna ska det tolkas som felaktigt indata och resultera i ett felmeddelande med felkod 2002 för felaktig input data.



De koder som API:et stöder för attributet lang finns listade nedan. Skickas det in en kod som inte stöds av API:et används default-kod istället.

Koder som API:et stöder för attributet lang:

  • sv (default)


Exempel: <fi2equipment_name lang="sv">S-14237645</fi2equipment_name>



De enheter som stöds av API:et finns listade nedan tillsammans med den enhet som är Default. Skickas det in en kod för attributet unit som inte stöds av API:et defaultas det tillbaka till default-kod.

Areaenhet:

  • m2 (default)
Exempel: <fi2area_value unit="m2">777</fi2area_value>

Längdenhet:
  • m (default)

Volymenhet:
  • m3 (default)
  • l

Energi:
  • kWh (default)
  • MWh

Prisenhet:
  • kr (default)

Kostnadsenhet:
  • kr/m3 (default)
  • kr/kWh
  • kr/MWh
  • kr/l



Anges en teckenkodning i xml-deklarationen som inte stöds av API:et hanteras det som felaktigt data. Det vill säga felkod 2002 returneras.
Exempel på felaktig xml-deklaration: <?xml version="1.0" encoding="UTF-16" ?>

Teckenkodning som stöds av API:et:

  • UTF-8


Det är fi2 xsd som bestämmer fältlängderna för alla fält i xml:en. Det är sedan upp till varje implementationen att hantera hur dessa värden lagras i bakomliggande databas.

Det är inte felaktigt data om till exempel en sträng på 50 tecken skickas in till ett system som endast kan lagra 30 tecken.

Skickar man in ett tal som är större än en int i ett fält som är definierat som int, så är detta felaktigt data och 2002 ska returneras.




Klasslistor ska alltid anges enligt API Datamodell för respektive entitet. De generella klasslistorna innehåller översättning av en egenskap till SABO-standarden.

Det är möjligt att komplettera med egna, implementationsspecifika klasslistor men de kommer inte ha stöd för filter och order. Observera att det då handlar om komplettering med klasser som finns i en specifik implementation, en entitet måste alltid ha ett värde från standardlistan.
API-implementationen ansvarar för att på bästa möjliga sätt översätta från implementationsspecifika klasser till generella klasser.


Exempel :


Under API Datamodell finns egenskaper angivna för respektive entitet

  • ReadOnly är fält som endast kan läsas
  • Required är fält som är obligatoriska, och måste stödjas av leverantören av API:et.
Observera att alla fält som kan skickas efter uppslagning eller beräkning ska betraktas som obligatoriska.
Om ett fält inte stöds ska det inte skickas med.


Ytterligare fält, t ex ett extra Id kan anges. Man måste då förutom id:t även hänvisa till den egna lista. Även här handlar det om en komplettering, man måste ange ett Id från standardlistan.

När parent eller child anges kan de kompletteras med ytterligare idenfierare, genom att man anger en usage.

Vid använding usage-attributet default måste det angivas på samma sätt som för andra usage.

Varje unik kombination av fält och usage kan endast användas en gång per objekt.



En ReadOnly-entitet består endast av fält som har egenskapen ReadOnly. Dessa entiteter stödjer inte POST- eller PUT-operationer, och saknar följande fält:

  • CreatedBy
  • CreatedDate
  • ChangedBy
  • ChangedDate
  • ETag


Med undantag för ReadOnly-entiteter har samtliga entiteter ett antal API-genererade fält. De sätts då posterna tillkommit eller förändrats i den underliggande datakällan. De syftar alltså inte till när det verkliga objektet skapats.

  • CreatedBy
    Användare som skapat posten
  • CreatedDate
    Datum och tid då posten skapades
  • ChangedBy
    Användare som senast förändrat posten
  • ChangedDate
    Datum och tid då posten senast förändrats

Dessa fält behöver inte skickas med från klienten vid skapande av nya objekt eller uppdatering av befintliga objekt. Fälten ska hanteras av API-implementationen, och sättas vid operationerna beroende på aktuell tidpunkt och användare.


Fält som sätts vid skapande av nya objekt:
  • CreatedBy
  • CreatedDate
  • ChangedBy
  • ChangedDate
Fält som sätts vid uppdatering av befintliga objekt:
  • ChangedBy
  • ChangedDate

CreatedDate och CreatedBy

Om information om CreatedDate och CreatedBy saknas i underliggande system ska detta hanteras av API-implementationen. Ur API:ets perspektiv ska dessa fält alltid innehålla giltiga värden. Saknas värde i underliggande system ska de värden som av verksamheten anses vara bäst överensstämmande med verkligheten returneras.

ChangedDate och ChangedBy

I de fall då ChangedDate och ChangedBy inte sätts till något värde då en post skapas av det underliggande systemet, ska API:et automatiskt hantera att dessa värden ur API:ets perspektiv anges till de värden som finns i CreatedDate och CreatedBy. Detta för att möjliggöra uttag av samtliga poster från en entitet som har skapats eller förändrats efter ett visst datum. Ur API:ets perspektiv ska dessa fält alltid innehålla giltiga värden.

Exempel:
  1. Ett utrymme ”Förrådet” skapas i underliggande system
  2. Underliggande system sätter CreatedDate och Created by, men inte ChangedDate och ChangedBy
  3. Vid följande fråga mot API:et ges träff på den nyskapade posten ”Förrådet” och andra poster som skapats denna dag : /api/fi2space/?filter=fi2space_value.fi2value_code[ChangedDate]>:'{Dagens Datum}'
  4. I svarsxml:en för anropet är fälten ChangedDate och ChangedBy angivna till motsvarande värde i CreatedDate och CreatedBy

Notera att underliggande system som alltid sätter ChangedDate och ChangedBy vid skapande av en ny post inte berörs av detta förfarande.


Primärnycklar

Då API:et är Master för entiteten ansvarar det för generering av nya primärnycklar. Vid skapande av nya objekt behöver då inte en primärnyckel skickas med objektet. API:et ansvarar för att skapa ett Id tillsammans med objektet och returnera objektet inklusive primärnyckel. Ifall en primärnyckel ändå skickats med, kommer det ignoreras av API:et.



Där kardinalitet är angivet i kolumnen Datatyp, är det det antalet upprepningar av fältet som ska stödjas.

Exempel: Address [0..n]

Utöver det ska även flera klasskoder stödjas då API:et implementerat stöd för implementationsspecifika klasslistor.


För övriga fält ska inte upprepning stödjas.



Alla entiteter har fält som betecknar start- och slutdatum för entiteten. För de Fi2-entiteter som har motsvarande fält som dedikerat fi2fält, t ex StartingDate under Fi2SpatiSystem, ska det fältet betraktas som ReadOnly och spegla värdet i StartDate. På samma sätt gäller för EndDate.



Länkar till dokument ska vara av typen http. Filer måste vara åtkomliga på samma nivå som API:et.



Det är xsd:n som bestämmer vilken datatyp ett fält har. Värden för värde- och usage-fält är undantaget detta. Vilken datatyp dessa värden har finns då definierade i dess värde- och usage-lista.



API:et ska returnera samtliga fält för datum och tid i samma tidszon.