Dokumentation för Tempus REST-API V1.0

URL

Grundadressen för denna version av APIet är:
https://rest.tempusinfo.se/tempusRest/admin/v1

Bygg sedan på den för att anropa specifika resurser.
Exempelvis:
https://rest.tempusinfo.se/tempusRest/admin/v1/counties
https://rest.tempusinfo.se/tempusRest/admin/v1/schools

Svengelska?

Du märker nog att vissa texter här i dokumentationen är på engelska medan andra är på svenska.
Det beror på att vårt verktyg för dokumentationsgenerering (Enunciate) inte har komplett stöd för översättning ännu.
Vi prioriterar i dagsläget tydlighet och enkelhet framför enhetlighet i dokumentationen, därför skriver vi våra egna kommentarer på svenska och låter autotexten vara på engelska tills vidare.

Krav för anrop / autentisering

Vi kan börja med några grundläggande krav som finns för anrop mot Tempus API.
Nedan följer några HTTP-headers som krävs vid varje anrop.

API-nyckel

Alla appar som kommunicerar med Tempus via vårt API behöver en unik API-nyckel.
Kontakta oss för att få en egen nyckel till just ditt system.
API-nyckeln anges i headern x-api-key.
Exempel: x-api-key: abc123.

Autentisering av API-användare

Alla anrop mot vårt API autentiseras utöver API-nycken med standard HTTP Basic authentication. Se W3-spec eller Wikipedia
Alltså användarnamn:lösenord enkodat i basen 64.
Exempel: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Användarnamnet får du också av oss, säg till i förväg om du vill välja det själv.

Lösenordet i autentiseringen väljer du själv efter att du fått API-nyckeln och användarnamnet.
Anropa resursen POST https://rest.tempusinfo.se/tempusRest/admin/v1/api_user/{ditt_användarnamn}/password
(Se mer information genom att klicka på själva resursen nedan)

Kund/kommun

Alla anrop till APIet måste kopplas till enskilda kunder (kommuner i normalfallet), detta görs via headern x-county.
Exempel: x-county: tempus-demo.
Kommunkoderna kan listas via ett GET till /counties.
Ingen autentisering behövs för detta anrop. Testa själv!

Content type och UTF-8?

Vi jobbar enbart med data i teckenkodningen UTF-8.
Följande headers måste vara satta för hämtning respektive sändning av data.

Tillåtna värden för headern accept (vid hämtning från Tempus)
application/json;charset=UTF-8
application/xml;charset=UTF-8

Tillåtna värden för headern content-type (vid sändning till Tempus)
application/json;charset=UTF-8
application/xml;charset=UTF-8

Anrop till enskilda resurser via id-nummer

Tempus interna id-nummer

För att komma åt viss data i vårt API använder man Tempus interna id-nummer för datat.
T.ex. returnerar GET på /districts/4 information om distrikt med id=4 i Tempus.
För att få en lista på vilka distrikt som finns i kommunen anropars GET på /districts (alltså utan id-nummer.
Anropen är nästlade ett steg, så man kan t.ex. anropa GET /districts/4/schools för att få en lista på enheterna i skolområde 4.
Och sedan kan man anropa GET /schools/45/departments för att få en lista på avdelningarna på enhet med id 45.

Externa id-nummer

Om din API-klient inte kan lagra Tempus interna id-nummer för viss data finns ett visst stöd för att istället skicka in externa id-nummer.
Detta gäller i dagsläget kommuners avdelningar.
Om du ser ordet "sync" framför vissa resurser och datatyper betyder det att de jobbar via externa idn istället för Tempus interna.

Felmeddelanden

Vid eventuella fel vid anrop till apiet returneras ett 4XX eller 5XX-svar beroende på felet i fråga.
T.ex. returneras 404 vid anrop till en resurs som inte finns, och 405 vid anrop till en resurs med fel anropstyp (t.ex. en POST till en resurs som redan finns).
I svaret följer även ett ErrorResponseMessage-objekt som kan innehålla mer information om varför felet uppkom.
T.ex ifall vår databas upptäckte att datan som stoppades in var felformatterad eller innehöll "olagliga" poster.
ErrorResponseMessage finns beskriven nedan under "Data Elements".
Vid valideringsfel med XML får man ValidationError istället för ErrorResponseMessage.

Resources

The resources use a data model that is supported by a set of client-side libraries that are made available on the files and libraries page.

name path methods description
ApiUser
  • /api_user/privileges
  • /api_user/timeout/{timeout_seconds}
  • /api_user/{external_system}/password
  • GET
  • GET
  • POST PUT
Härifrån kan du hantera lösenordet till din API-användare/externa system
Children
  • /children
  • /children/sync_id/{syncId}
  • GET PUT
  • DELETE
Via dessa resurser hanteras barninformationen i Tempus.
ChildrenAbsence
  • /children/ssn/{childSsn}/absence
  • /children/ssn/{childSsn}/absence/{date}
  • POST
  • GET POST
Via denna resurs kan frånvaroanmälningar sparas i Tempus.
Counties
  • /counties
  • GET
Via denna resurs kan en lista på Tempus kommuner/kunder erhållas.
Ingen autentisering krävs.
Departments
  • /departments
  • /departments/{departmentId}/child_avatars
  • /departments/{departmentId}/child_names
  • /departments/{departmentId}/children
  • GET
  • GET
  • GET
  • GET
Via dessa resurser hanteras avdelningarna i Tempus.
DepartmentsChildTimes
  • /departments/{departmentId}/absences
  • /departments/{departmentId}/attendance
  • /departments/{departmentId}/on_leaves
  • /departments/{departmentId}/schedules
  • GET
  • GET
  • GET
  • GET
Här kan du hämta barnens tider via avdelningars idn.
Districts
  • /districts
  • GET
Via dessa resurser hanteras skolområdena i Tempus.
Emails
  • /emails/{email}
  • GET
Via dessa resurser hanteras e-post i Tempus.
Schools
  • /schools
  • GET
Via dessa resurser hanteras enheterna i Tempus.
SyncChildTypeDateRanges
  • /sync_child_type_date_ranges
  • POST
Via denna resurs hanteras barnens "placeringstyper" (serviceformer/taxekategorier) via objektens externa sync-idn.
SyncDepartments
  • /sync_departments
  • /sync_departments/access
  • /sync_departments/{departmentSyncId}
  • PUT
  • POST PUT
  • DELETE GET PUT
Via dessa resurser hanteras avdelningarna i Tempus med hjälp av deras externa sync-idn.
SyncDepartmentsChangeHistory
  • /sync_departments/{departmentSyncId}/change_history
  • GET
Här kan du hämta kalenderhändelser avdelningars synk-idn.
SyncDepartmentsChildTimes
  • /sync_departments/{departmentSyncId}/absences
  • /sync_departments/{departmentSyncId}/attendance
  • /sync_departments/{departmentSyncId}/on_leaves
  • /sync_departments/{departmentSyncId}/schedules
  • GET
  • GET
  • GET
  • GET
Här kan du hämta barnens tider via avdelningars synk-idn.
SyncDistricts
  • /sync_districts
  • PUT
Via dessa resurser hanteras skolområdena i Tempus.
SyncEnrollments
  • /sync_enrollments
  • POST
Via denna resurs hanteras barnens placeringar på förskolorna, via avdelningarnas externa sync-idn.
SyncRoles
  • /sync_roles
  • POST
SyncSchools
  • /sync_schools
  • PUT
Via dessa resurser hanteras enheterna i Tempus via deras externa synk-idn.
SyncUsers
  • /sync_users
  • /sync_users/sync_children
  • /sync_users/{userSyncId}
  • /sync_users/{userSyncId}/sync_children/{childSyncId}
  • /sync_users/{userSyncId}/sync_departments/{departmentSyncId}
  • PUT
  • POST PUT
  • DELETE
  • DELETE
  • DELETE
Anropas för hantering av användare från system som inte kan lagra Tempus-användar-idn.
Users
  • /users
  • /users/{userId}
  • /users/{userId}/departments
  • GET
  • DELETE
  • GET
Anropas för hantering av användare (föräldrar eller personal/administratörer) i Tempus.

Data Types

JSON

type description
AbsenceHistory
AbsenceInfo Samlingsobjekt för information om en frånvaroanmälan i Tempus.
AbsenceTime Samlingsobjekt för information om frånvaroanmälan för ett visst datum.
AdminUserInfo Information om en personal eller administratör i Tempus
AdminUserPrivilege
ApiPrivilege
Child Samlingsobjekt för ett barns id samt information om barnet Tempus.
ChildAvatar Samlingsobjekt för ett barns id samt en URL till dess visningsbild.
ChildAvatarList En lista med barnbilder
ChildChangeHistory Listor med ändringshistorik (ett visst datum) för ett visst barn.
ChildInfo Samlingsobjekt för information om ett barn i Tempus.
ChildList En lista med barn
ChildName Samlingsobjekt för ett barns id samt dess för och efternamn.
ChildNameList En lista med barnnamn
ChildTimes En lista med tider (ett visst datum) för ett visst barn.
Innehåller också barnets "viktning" datumet i fråga.
ChildTypeInfo Samlingsobjekt för information om en placeringstyp/serviceform
ChildTypeTimeSpan Informationsobjekt för en barntypsperiod, dvs Vilken barntyp barnet har mellan två datum.
County En kommun/kund i Tempus.
CountyList En lista över kommunerna/kunderna i Tempus.
DateChildChangeHistory En lista med barn (och deras ändringshistorik) ett visst datum.
DateChildChangeHistoryList En lista med datum som innehåller data
DateChildTimes En lista med ChildTimes (barn och deras tider) ett visst datum.
DateChildrenOnLeave Ett datum samt en lista med vilka barn som är lediga då
DateOnLeaveList En lista med datum som innehåller information om vilka barn som är lediga då
DateOnly A representation of a ISO-8601 standard calendar date.
DateTimeList En lista med DateChildTimes
Department En avdelning på en förskola/fritids
DepartmentInfo Information om en förskole-/fritidsavdeling
DepartmentList En lista med avdelningar
DepartmentType
District Information om ett skolområde
DistrictInfo Samlingsobjekt för information om ett skolområde
DistrictInfoList En lista med skolområden
DistrictList En lista med skolområden
EmailInfo Samlingsobjekt för en användares epost-information.
Enrollment Ett barns placering i Tempus.
Placeringens id getEnrollmentId kan utelämnas om det gäller en placering som ännu inte lagrats i Tempus.
OnLeaveChild
ParentUserInfo Information som gäller föräldaanvändare i Tempus
ScheduleHistory
School Information om en förskola/ett fritids
SchoolInfo
SchoolInfoList En lista med förskolor/fritids
SchoolList En lista med förskolor/fritids
SyncChildTypeDateRange
SyncChildTypeDateRangeList En lista med ny barntypsinformation som ska läsas in i Tempus och ersätta barntyperna mellan de givna datumen.
SyncDepartmentAccess
SyncDepartmentAccessList En lista med information om vilka användare som kommer åt vilka avdelningar. Inga interna Tempus-IDn finns i denna datatyp.
SyncDepartmentInfo
SyncDepartmentInfoList En lista med information om avdelningar. Inga interna Tempus-IDn finns i denna datatyp.
SyncEnrollment
SyncRole
SyncRoleList En lista med information om vilka användare som har vilka roller och när. Inga interna Tempus-IDn finns i denna datatyp.
SyncUserChildConnection
SyncUserChildConnectionList En lista med vilka användare som är kopplade till vilka barn.
TempusAdminUser
TimeSpan
TimeSpanWithModified
UpdateChildInfo Samlingsobjekt för information som ska uppdateras om ett barn i Tempus.
Alla fält är valfria, men att sätta ett fält till null är samma som att inte ens ta med det (det kommer alltså ignoreras i båda fallen).
UpdateChildInfoList En lista med barninformation som ska uppdateras i Tempus.
UpdateSyncEnrollment
UpdateSyncEnrollmentList En lista med ny placeringsinformation som ska läsas in i Tempus och ersätta placeringarna mellan de givna datumen.
UpdateUserInfo Information om en användare från ett externt system som antingen ska uppdateras eller läggas till i Tempus.
UpdateUserInfoList En lista med användarinformation som ska uppdateras eller läggas till i Tempus.
User Innehåller information om en användare (förälder eller personal/administratör)
UserDataInfo Gemensam information för föräldrar och personal/administratörer i Tempus
UserIdentification Identifieringsalternativ för en användare
UserInfo Samlingsobjekt för information om en användare i Tempus.
UserList En lista med Tempus-användare (förälder eller personal/administratör)

XML

Default Namespace
type description
apiPrivilege
Namespace tempus.common.shared.wrapper.enums-v1
type description
userPrivilege
Namespace http://www.tempusinfo.se/tempusRest/admin/v1.0
type description
absenceHistory
absenceInfo Samlingsobjekt för information om en frånvaroanmälan i Tempus.
absenceTime Samlingsobjekt för information om frånvaroanmälan för ett visst datum.
adminUserInfo Information om en personal eller administratör i Tempus
adminUserPrivilege
child Samlingsobjekt för ett barns id samt information om barnet Tempus.
childAvatar Samlingsobjekt för ett barns id samt en URL till dess visningsbild.
childAvatarList En lista med barnbilder
childChangeHistory Listor med ändringshistorik (ett visst datum) för ett visst barn.
childInfo Samlingsobjekt för information om ett barn i Tempus.
childList En lista med barn
childName Samlingsobjekt för ett barns id samt dess för och efternamn.
childNameList En lista med barnnamn
childTimes En lista med tider (ett visst datum) för ett visst barn.
Innehåller också barnets "viktning" datumet i fråga.
childTypeInfo Samlingsobjekt för information om en placeringstyp/serviceform
childTypeTimeSpan Informationsobjekt för en barntypsperiod, dvs Vilken barntyp barnet har mellan två datum.
county En kommun/kund i Tempus.
countyList En lista över kommunerna/kunderna i Tempus.
dateChildChangeHistory En lista med barn (och deras ändringshistorik) ett visst datum.
dateChildChangeHistoryList En lista med datum som innehåller data
dateChildTimes En lista med ChildTimes (barn och deras tider) ett visst datum.
dateChildrenOnLeave Ett datum samt en lista med vilka barn som är lediga då
dateOnLeaveList En lista med datum som innehåller information om vilka barn som är lediga då
dateOnly A representation of a ISO-8601 standard calendar date.
dateTimeList En lista med DateChildTimes
department En avdelning på en förskola/fritids
departmentInfo Information om en förskole-/fritidsavdeling
departmentList En lista med avdelningar
departmentType
district Information om ett skolområde
districtInfo Samlingsobjekt för information om ett skolområde
districtInfoList En lista med skolområden
districtList En lista med skolområden
emailInfo Samlingsobjekt för en användares epost-information.
enrollment Ett barns placering i Tempus.
Placeringens id getEnrollmentId kan utelämnas om det gäller en placering som ännu inte lagrats i Tempus.
onLeaveChild
parentUserInfo Information som gäller föräldaanvändare i Tempus
scheduleHistory
school Information om en förskola/ett fritids
schoolInfo
schoolInfoList En lista med förskolor/fritids
schoolList En lista med förskolor/fritids
syncChildTypeDateRange
syncChildTypeDateRangeList En lista med ny barntypsinformation som ska läsas in i Tempus och ersätta barntyperna mellan de givna datumen.
syncDepartmentAccess
syncDepartmentAccessList En lista med information om vilka användare som kommer åt vilka avdelningar. Inga interna Tempus-IDn finns i denna datatyp.
syncDepartmentInfo
syncDepartmentInfoList En lista med information om avdelningar. Inga interna Tempus-IDn finns i denna datatyp.
syncEnrollment
syncUserChildConnection
syncUserChildConnectionList En lista med vilka användare som är kopplade till vilka barn.
tempusAdminUser
timeSpan
timeSpanWithModified
updateChildInfo Samlingsobjekt för information som ska uppdateras om ett barn i Tempus.
Alla fält är valfria, men att sätta ett fält till null är samma som att inte ens ta med det (det kommer alltså ignoreras i båda fallen).
updateChildInfoList En lista med barninformation som ska uppdateras i Tempus.
updateSyncEnrollment
updateSyncEnrollmentList En lista med ny placeringsinformation som ska läsas in i Tempus och ersätta placeringarna mellan de givna datumen.
updateUserInfo Information om en användare från ett externt system som antingen ska uppdateras eller läggas till i Tempus.
updateUserInfoList En lista med användarinformation som ska uppdateras eller läggas till i Tempus.
user Innehåller information om en användare (förälder eller personal/administratör)
userDataInfo Gemensam information för föräldrar och personal/administratörer i Tempus
userIdentification Identifieringsalternativ för en användare
userInfo Samlingsobjekt för information om en användare i Tempus.
userList En lista med Tempus-användare (förälder eller personal/administratör)