REST API

De Ultimo REST API is de primaire interface voor het programmatisch ophalen, invoegen, bijwerken en verwijderen van data in Ultimo. De API is beschikbaar sinds versie 18.04 (2018R2) en gebruikt JSON als standaard dataformaat met OData v4 query opties.

Beschikbaarheid: Professional, Premium, Enterprise

Setupbewerken

Voordat je de REST API kunt gebruiken, moet je een API key aanmaken in de Ultimo Configuration Tool (UCT). Zie api-keys voor uitgebreide instructies.

Vereisten: - Een actieve API key met de juiste entiteiten en properties geconfigureerd - HTTPS-verbinding naar de Ultimo omgeving - Optioneel: API key template voor snelle configuratie

URL Structuurbewerken

Alle REST API requests volgen deze structuur:

https://{service-root}/api/v1/object/{resource-path}?{query-options}

Authenticatiebewerken

Elke request vereist een API key in de header:

ApiKey: {API KEY SECRET}

Beschikbare headersbewerken

Autorisatiebewerken

Record-level autorisatie is gekoppeld aan de systeemgebruiker die aan de API key is gelinkt. Toegang wordt beperkt op basis van afdelingstoewijzingen.

GET - Data ophalenbewerken

De GET methode haalt informatie op uit Ultimo.

Voorbeelden van resource padenbewerken

Voorbeeld: Equipment ophalenbewerken

Request:

GET https://customer.ultimo.net/api/v1/object/Equipment('00001')
ApiKey: abc123def456

Response:

{
  "Id": "00001",
  "Context": 1,
  "Description": "Koelinstallatie gebouw A",
  "InstallDate": "2022-04-07",
  "ManufactureYear": 2020,
  "NextPmMaintenanceDate": "2023-04-07",
  "Status": 2,
  "SerialNumber": "SN-2020-0042",
  "CostCenter": "01",
  "Department": "01",
  "EquipmentType": "HVAC",
  "PartOfEquipment": "GEBOUW-A"
}

Pagineringbewerken

De API gebruikt server-side paginering. De eerste pagina bevat een nextPageLink voor vervolgpagina's:

{
  "nextPageLink": "https://customer.ultimo.net/api/v1/object/Equipment?$skip=100",
  "items": [...]
}

Belangrijk: Gebruik altijd de meegeleverde nextPageLink om alle records op te halen. Bouw geen eigen paginering-logica.

External Identifiersbewerken

Gebruik ExternalId voor identificatie vanuit externe systemen. De combinatie ExternalId + DataProvider is uniek.

GET .../object/Equipment(ExternalId='EXT001')
GET .../object/Equipment(ExternalId='EXT001',DataProvider='SAP')

Meertalige outputbewerken

Bij meertalige configuratie worden alle beschikbare talen als genest object teruggegeven:

{
  "Description": {
    "NL": "Koelinstallatie",
    "EN": "Cooling unit",
    "DE": "Kuhlanlage"
  }
}

PUT - Invoegen of bijwerkenbewerken

PUT voegt een nieuw record in of werkt een bestaand record bij op basis van de opgegeven identifier.

Verplichte properties: Context, Status

Voorbeeld: Equipment aanmaken/bijwerken

PUT https://customer.ultimo.net/api/v1/object/Equipment('00001')
Content-Type: application/json
ApiKey: abc123def456

{
  "Context": 1,
  "Description": "Koelinstallatie gebouw A",
  "InstallDate": "2022-04-07",
  "NextPmMaintenanceDate": "2023-04-07",
  "Status": 2,
  "CostCenter": "01",
  "Department": "01"
}

Let op: Bij PUT worden niet-opgegeven properties teruggezet naar hun standaardwaarde of null.

POST - Nieuw record invoegenbewerken

POST maakt een nieuw record aan zonder identifier (alleen voor entiteiten met autokey).

Voorbeeld: Nieuwe Job aanmaken

POST https://customer.ultimo.net/api/v1/object/Job
Content-Type: application/json
ApiKey: abc123def456

{
  "Context": 1,
  "Status": 1,
  "Description": "Storing koelinstallatie",
  "Equipment": "00001",
  "Department": "01"
}

Response:

{
  "Id": "39938",
  "Context": 1,
  "Status": 1,
  "Description": "Storing koelinstallatie",
  "Equipment": "00001",
  "Department": "01"
}

PATCH - Enkel property bijwerkenbewerken

PATCH werkt specifieke properties bij zonder andere velden te beinvloeden.

Voorbeeld:

PATCH https://customer.ultimo.net/api/v1/object/Equipment('00001')
Content-Type: application/json
ApiKey: abc123def456

{
  "Description": "Koelinstallatie gebouw B"
}

DELETE - Record verwijderenbewerken

DELETE verwijdert een specifiek record.

DELETE https://customer.ultimo.net/api/v1/object/Equipment('00001')
ApiKey: abc123def456

Batch operatiesbewerken

Voor het verwerken van meerdere records in een enkele request.

Endpoint:

POST https://customer.ultimo.net/api/v1/batch

Beperkingen: - Maximaal 100 records per batch request - Maximale payload: 1 MB

Request structuurbewerken

{
  "requests": [
    {
      "id": "req1",
      "method": "PUT",
      "url": "/api/v1/object/Equipment('00001')",
      "body": {
        "Context": 1,
        "Status": 2,
        "Description": "Asset A"
      }
    },
    {
      "id": "req2",
      "method": "PUT",
      "url": "/api/v1/object/Equipment('00002')",
      "body": {
        "Context": 1,
        "Status": 2,
        "Description": "Asset B"
      }
    }
  ]
}

Atomicity groupsbewerken

Groepeer requests voor transactie-verwerking met atomicityGroup:

{
  "requests": [
    {
      "id": "req1",
      "method": "PUT",
      "url": "/api/v1/object/Equipment('00001')",
      "body": { "Context": 1, "Status": 2, "Description": "Asset A" },
      "atomicityGroup": "groep1"
    },
    {
      "id": "req2",
      "method": "PUT",
      "url": "/api/v1/object/Equipment('00002')",
      "body": { "Context": 1, "Status": 2, "Description": "Asset B" },
      "atomicityGroup": "groep1"
    }
  ]
}

Dependenciesbewerken

Gebruik dependsOn om afhankelijkheden tussen requests aan te geven:

{
  "id": "req2",
  "method": "PUT",
  "url": "/api/v1/object/Equipment('00002')",
  "body": { "Context": 1, "Status": 2 },
  "dependsOn": ["req1"]
}

Batch response codesbewerken

File uploadsbewerken

Twee methoden voor het uploaden van bestanden:

Multipart/form-data (aanbevolen)bewerken

curl --location "https://customer.ultimo.net/api/v1/action/_REST_UploadFile" \
  --header "applicationelementid: 99999999-9999-9999-9999-999999999999" \
  --header "apikey: abc123def456" \
  --form "File=@C:/temp/Rapport.pdf" \
  --form "JobId=123456789"

Aanbeveling: Gebruik multipart/form-data in plaats van Base64. Base64 encoding vergroot het bestand met circa 33%.

Limieten voor uploadsbewerken

Query opties (OData)bewerken

Zie odata-filters voor een uitgebreide referentie van alle OData filter opties.

Snel overzichtbewerken

GET .../object/Equipment?$filter=Status eq 2&$select=Id,Description&$top=10&$orderby=Description asc

Foutafhandelingbewerken

Zie de volledige lijst bij API overzicht.

HTTP response codesbewerken

Belangrijk: Een 200 OK response betekent alleen dat de request is ontvangen, niet dat deze succesvol is verwerkt door Ultimo. Controleer altijd de response body.

Limieten en quotabewerken

Individuele API keys kunnen een eigen dagelijks quotum krijgen voor verdeling over meerdere partijen.

Aanvullende beveiliging (Azure)bewerken

IP Filteringbewerken

Per API key kan een IP-adresreeks worden geconfigureerd als whitelist: - Gebruik - voor bereiken, ; voor meerdere bereiken - Ondersteunt IPv4 en IPv6 - Als slechts een protocol is geconfigureerd, wordt het andere geblokkeerd

Client Certificatesbewerken

Per API key kan een certificaat-thumbprint worden ingesteld. Bij gebruik van certificaten wijzigt de endpoint URL:

Testenbewerken

Ultimo genereert API key-specifieke Swagger documentatie met alle beschikbare commando's en testfunctionaliteit.

Speciale tekensbewerken

Forward slashes in IDsbewerken

Forward slashes worden als pad-scheiders geinterpreteerd. Gebruik een filter als alternatief:

# Werkt NIET:
GET .../object/Building('01/02')

# Werkt WEL:
GET .../object/Building?filter=Id eq '01/02'

Beperkte tekens in IDsbewerken

De volgende tekens zijn niet toegestaan: < > * % & : \ ?

Gebruik URL encoding:

GET .../object/Building?filter=Id+eq+'%3C%3E*%25%26%3A%3F'

Aanhalingstekens in filtersbewerken

Enkele aanhalingstekens in filterwaarden moeten verdubbeld worden:

GET .../object/Building?filter=Description eq 'single''quote'

Gerelateerde artikelenbewerken

• api-keys -- API keys aanmaken en beheren
• odata-filters -- Uitgebreide OData filter referentie
• http-post -- Alternatief: HTTP POST integratie
• soap -- Alternatief: SOAP/WCF integratie
• import-connectors -- Data importeren via connectors
• export-connectors -- Data exporteren via connectors