Erste Schritte mit der InLoox API

Dieser Leitfaden hilft Ihnen, die Authentifizierung einzurichten, die Grundlagen von OData zu verstehen und Ihre erste API-Anfrage zu senden.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie:

Ein aktives InLoox-Konto (Cloud oder Self-Hosted)
Einen Personal Access Token (API-Token) — diesen können Sie in InLoox unter Datei → Optionen → Persönliche Zugriffsschlüssel erstellen
Ein HTTP-Client wie cURL, Postman oder eine Programmiersprache Ihrer Wahl

Token erstellen

Navigieren Sie in InLoox zu Datei → Optionen → Persönliche Zugriffsschlüssel und klicken Sie auf Neuen Schlüssel erstellen. Kopieren Sie den generierten Token — er wird nur einmal angezeigt.

Schützen Sie Ihren Token

Ihr Personal Access Token gewährt vollen Zugriff auf die API in Ihrem Namen. Behandeln Sie ihn wie ein Passwort — committen Sie ihn niemals in die Versionskontrolle und teilen Sie ihn nicht öffentlich.

Authentifizierung

Die InLoox API verwendet Personal Access Tokens zur Authentifizierung. Senden Sie Ihren Token bei jeder Anfrage als x-api-key-HTTP-Header mit.

cURL

curl -X GET "https://app.inloox.com/api/odata/Project" \
  -H "x-api-key: YOUR_API_TOKEN"

C# (HttpClient)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_TOKEN");

var response = await client.GetAsync("https://app.inloox.com/api/odata/Project");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

C# (Simple.OData.Client)

var settings = new ODataClientSettings(new Uri("https://app.inloox.com/api/odata/"));
settings.BeforeRequest += delegate (HttpRequestMessage message)
{
    message.Headers.Add("x-api-key", "YOUR_API_TOKEN");
};
var client = new ODataClient(settings);

JavaScript (fetch)

const response = await fetch("https://app.inloox.com/api/odata/Project", {
  headers: {
    "x-api-key": "YOUR_API_TOKEN"
  }
});
const data = await response.json();
console.log(data);

Token überprüfen

Eine schnelle Möglichkeit, Ihren Token zu testen, ist der Aufruf des AccountInfo-Endpunkts:

curl -X GET "https://app.inloox.com/api/odata/AccountInfo" \
  -H "x-api-key: YOUR_API_TOKEN"

Bei erfolgreicher Authentifizierung erhalten Sie Ihre Benutzerprofilinformationen.

Basis-URL

Verwenden Sie die passende Basis-URL je nach Ihrer InLoox-Bereitstellung:

Bereitstellung	Basis-URL
InLoox Cloud	`https://app.inloox.com/api/odata/`
InLoox Self-Hosted	`https://YOUR-SELF-HOSTED-URL/api/v1/odata/`

Alle Endpunkt-Pfade in dieser Dokumentation sind relativ zur Basis-URL. Zum Beispiel:

Project → https://app.inloox.com/api/odata/Project
TimeEntry → https://app.inloox.com/api/odata/TimeEntry

OData-Grundlagen

Die InLoox API basiert auf dem OData-Protokoll (Open Data Protocol). OData stellt eine standardisierte Abfragesprache bereit, mit der Sie Daten filtern, sortieren, auswählen und paginieren können — direkt über die URL.

Was ist OData?

OData ist ein offener Standard für den Aufbau und die Nutzung von REST APIs. Er definiert bewährte Muster für Abfragen, die über URL-Parameter ($filter, $select, $orderby usw.) gesteuert werden. So können Sie präzise steuern, welche Daten Sie erhalten, ohne dass spezielle Endpunkte erforderlich sind.

`$filter` — Daten filtern

Mit $filter schränken Sie die zurückgegebenen Datensätze anhand von Bedingungen ein.

Projekte nach Name filtern:

curl -X GET "https://app.inloox.com/api/odata/Project?\$filter=Name eq 'Mein Projekt'" \
  -H "x-api-key: YOUR_API_TOKEN"

Projekte, die nach einem bestimmten Datum erstellt wurden:

curl -X GET "https://app.inloox.com/api/odata/Project?\$filter=CreatedDate gt 2024-01-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_TOKEN"

Mehrere Bedingungen kombinieren (and / or):

curl -X GET "https://app.inloox.com/api/odata/Project?\$filter=IsActive eq true and Name ne 'Archiviert'" \
  -H "x-api-key: YOUR_API_TOKEN"

Häufige Filteroperatoren:

Operator	Bedeutung	Beispiel
`eq`	Gleich	`Name eq 'Test'`
`ne`	Ungleich	`Status ne 'Closed'`
`gt`	Größer als	`CreatedDate gt 2024-01-01T00:00:00Z`
`lt`	Kleiner als	`Progress lt 50`
`ge`	Größer oder gleich	`Progress ge 80`
`le`	Kleiner oder gleich	`Progress le 100`
`and`	Logisches Und	`IsActive eq true and Progress gt 0`
`or`	Logisches Oder	`Status eq 'Open' or Status eq 'InProgress'`
`contains()`	Enthält	`contains(Name, 'Marketing')`
`startswith()`	Beginnt mit	`startswith(Name, 'Projekt')`

Zeichenkettenwerte in Filtern

Zeichenkettenwerte müssen in einfache Anführungszeichen eingeschlossen werden: Name eq 'Mein Projekt'. GUIDs und Datumsangaben benötigen keine Anführungszeichen.

// C# mit Simple.OData.Client
var projects = await client
    .For<ApiProject>("Project")
    .Filter(p => p.Name == "Website Redesign")
    .FindEntriesAsync();

`$select` — Felder auswählen

Mit $select bestimmen Sie, welche Eigenschaften in der Antwort zurückgegeben werden. Das reduziert die Datenmenge und verbessert die Performance.

curl -X GET "https://app.inloox.com/api/odata/Project?\$select=ProjectId,Name,StartDate,EndDate" \
  -H "x-api-key: YOUR_API_TOKEN"

C#-Beispiel:

var response = await client.GetAsync("Project?$select=ProjectId,Name,StartDate");

// C# mit Simple.OData.Client
var projects = await client
    .For<ApiProject>("Project")
    .Select(p => new { p.ProjectId, p.Name })
    .FindEntriesAsync();

`$orderby` — Sortierung

Mit $orderby sortieren Sie die Ergebnisse nach einer oder mehreren Eigenschaften.

Aufsteigend sortieren (Standard):

curl -X GET "https://app.inloox.com/api/odata/Project?\$orderby=Name" \
  -H "x-api-key: YOUR_API_TOKEN"

Absteigend sortieren:

curl -X GET "https://app.inloox.com/api/odata/Project?\$orderby=CreatedDate desc" \
  -H "x-api-key: YOUR_API_TOKEN"

Mehrere Sortierkriterien:

curl -X GET "https://app.inloox.com/api/odata/Project?\$orderby=IsActive desc,Name asc" \
  -H "x-api-key: YOUR_API_TOKEN"

// C# mit Simple.OData.Client
var projects = await client
    .For<ApiProject>("Project")
    .OrderBy(p => p.StartDate)
    .FindEntriesAsync();

`$top` und `$skip` — Paging

Verwenden Sie $top und $skip, um die Ergebnisse seitenweise abzurufen.

Parameter	Beschreibung	Beispiel
`$top`	Maximale Anzahl zurückgegebener Einträge	`$top=20`
`$skip`	Anzahl zu überspringender Einträge	`$skip=40`

Erste 20 Projekte:

curl -X GET "https://app.inloox.com/api/odata/Project?\$top=20" \
  -H "x-api-key: YOUR_API_TOKEN"

Seite 3 (Elemente 41–60):

curl -X GET "https://app.inloox.com/api/odata/Project?\$top=20&\$skip=40" \
  -H "x-api-key: YOUR_API_TOKEN"

// C# mit Simple.OData.Client
var page2 = await client
    .For<ApiProject>("Project")
    .Skip(10)
    .Top(10)
    .FindEntriesAsync();

`$count` — Gesamtanzahl

Mit $count erhalten Sie die Gesamtanzahl der Entitäten, die Ihrer Abfrage entsprechen.

# Gesamtanzahl der Projekte
curl "https://app.inloox.com/api/odata/Project/\$count" \
  -H "x-api-key: YOUR_API_TOKEN"

Sie können auch $count=true mit einer regulären Abfrage kombinieren, um die Anzahl zusammen mit den Daten in der Antwort einzuschließen:

curl "https://app.inloox.com/api/odata/Project?\$count=true&\$top=10" \
  -H "x-api-key: YOUR_API_TOKEN"

`$expand` — Verknüpfte Daten laden

Wenn ein Endpunkt $expand unterstützt, können Sie verknüpfte Entitäten in einer einzigen Anfrage mitladen.

curl "https://app.inloox.com/api/odata/Task?\$expand=Project" \
  -H "x-api-key: YOUR_API_TOKEN"

info

Nicht alle Endpunkte unterstützen $expand. Prüfen Sie die jeweilige Entitätsdokumentation für unterstützte Expansionen.

Abfrageoptionen kombinieren

Sie können mehrere Abfrageoptionen in einer einzigen Anfrage kombinieren:

# Top 5 offene Aufgaben in einem Projekt, sortiert nach Fälligkeitsdatum, nur Schlüsselfelder
curl "https://app.inloox.com/api/odata/Task?\$filter=ProjectId eq {projectId} and IsDone eq false&\$orderby=EndDate asc&\$top=5&\$select=TaskItemId,DisplayName,EndDate" \
  -H "x-api-key: YOUR_API_TOKEN"

Paginierung

Die API gibt standardmäßig maximal 100 Elemente pro Anfrage zurück. Um alle Datensätze abzurufen, müssen Sie durch die Seiten paginieren.

Paginierungsstrategie

Senden Sie eine Anfrage mit $top und optional $count=true
Prüfen Sie, ob die Antwort ein @odata.nextLink-Feld enthält
Wenn ja, senden Sie die nächste Anfrage an die im @odata.nextLink angegebene URL
Wiederholen Sie, bis kein @odata.nextLink mehr vorhanden ist

Funktionsweise der Paginierung

Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort eine @odata.nextLink-Eigenschaft mit der URL für die nächste Seite:

{
  "@odata.context": "https://app.inloox.com/api/odata/$metadata#Project",
  "value": [ ... ],
  "@odata.nextLink": "https://app.inloox.com/api/odata/Project?$skip=100"
}

Beispiel: Alle Projekte abrufen (C#)

var allProjects = new List<ApiProject>();
int skip = 0;
const int pageSize = 100;

while (true)
{
    var response = await client.GetAsync($"Project?$top={pageSize}&$skip={skip}");
    var json = await response.Content.ReadAsStringAsync();
    var page = JsonSerializer.Deserialize<ODataResponse<ApiProject>>(json);

    allProjects.AddRange(page.Value);

    if (page.Value.Count < pageSize)
        break;

    skip += pageSize;
}

Console.WriteLine($"Insgesamt {allProjects.Count} Projekte geladen.");

Paginierung mit Simple.OData.Client (C#)

Die ODataFeedAnnotations-Klasse verarbeitet die Paginierung automatisch:

var allEntries = new List<ApiProject>();
var annotations = new ODataFeedAnnotations();

var page = (await client
    .For<ApiProject>("Project")
    .FindEntriesAsync(annotations)).ToList();

allEntries.AddRange(page);

while (annotations.NextPageLink != null)
{
    page = (await client
        .For<ApiProject>("Project")
        .FindEntriesAsync(annotations.NextPageLink, annotations)).ToList();
    allEntries.AddRange(page);
}

Console.WriteLine($"Insgesamt geladene Projekte: {allEntries.Count}");

Hinweis zur Performance

Wenn Sie große Datensätze abrufen, verwenden Sie $filter, um die Abfrage einzuschränken, anstatt durch alle Datensätze zu paginieren. Dies reduziert sowohl den Netzwerkverkehr als auch die Serverlast.

Beispiel: Paginierung mit cURL

# Seite 1
curl -X GET "https://app.inloox.com/api/odata/Project?\$top=100&\$skip=0" \
  -H "x-api-key: YOUR_API_TOKEN"

# Seite 2
curl -X GET "https://app.inloox.com/api/odata/Project?\$top=100&\$skip=100" \
  -H "x-api-key: YOUR_API_TOKEN"

# Seite 3
curl -X GET "https://app.inloox.com/api/odata/Project?\$top=100&\$skip=200" \
  -H "x-api-key: YOUR_API_TOKEN"

Antwortformat

Alle API-Antworten werden im JSON-Format mit OData-Metadaten zurückgegeben.

Beispielantwort für eine Liste

{
  "@odata.context": "https://app.inloox.com/api/odata/$metadata#Project",
  "@odata.count": 42,
  "value": [
    {
      "ProjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "Name": "Website Relaunch",
      "StartDate": "2024-03-01T00:00:00Z",
      "EndDate": "2024-06-30T00:00:00Z",
      "IsActive": true
    }
  ]
}

Beispielantwort für ein einzelnes Objekt

{
  "@odata.context": "https://app.inloox.com/api/odata/$metadata#Project/$entity",
  "ProjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Name": "Website Relaunch",
  "StartDate": "2024-03-01T00:00:00Z",
  "EndDate": "2024-06-30T00:00:00Z",
  "IsActive": true
}

Wichtige Felder

Feld	Beschreibung
`@odata.context`	Metadaten-URL für den zurückgegebenen Entitätstyp
`@odata.count`	Gesamtanzahl der Datensätze (wenn `$count=true` angefordert)
`@odata.nextLink`	URL für die nächste Seite (bei paginierten Ergebnissen)
`value`	Array der zurückgegebenen Entitäten

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes, um den Erfolg oder Fehler einer Anfrage anzuzeigen.

Statuscode	Bedeutung	Beschreibung
`200 OK`	Erfolg	Die Anfrage war erfolgreich.
`201 Created`	Erstellt	Eine neue Ressource wurde erfolgreich erstellt.
`204 No Content`	Kein Inhalt	Die Anfrage war erfolgreich, es gibt keine Rückgabedaten (z. B. bei DELETE).
`400 Bad Request`	Fehlerhafte Anfrage	Die Anfrage ist ungültig — prüfen Sie die Parameter und den Request-Body.
`401 Unauthorized`	Nicht autorisiert	Der API-Token fehlt oder ist ungültig.
`403 Forbidden`	Zugriff verweigert	Sie haben keine Berechtigung für diese Ressource.
`404 Not Found`	Nicht gefunden	Die angeforderte Ressource existiert nicht.
`429 Too Many Requests`	Ratenbeschränkung	Zu viele Anfragen in einem kurzen Zeitraum.
`500 Internal Server Error`	Serverfehler	Ein interner Fehler ist aufgetreten — kontaktieren Sie den Support.

Fehlerantwort-Beispiel

{
  "error": {
    "code": "400",
    "message": "The query specified in the URI is not valid. Could not find a property named 'InvalidField' on type 'ApiProject'."
  }
}

Tipps zur Fehlerbehebung

401-Fehler: Prüfen Sie, ob der x-api-key-Header korrekt gesetzt ist und der Token gültig ist.
400-Fehler: Überprüfen Sie die Syntax Ihrer OData-Abfrage und die Feldnamen.
404-Fehler: Stellen Sie sicher, dass die Basis-URL und der Endpunkt-Pfad korrekt sind.
Prüfen Sie bei Bedarf die Schreibweise von Eigenschaftsnamen in $select, $filter und $orderby — diese sind groß-/kleinschreibungssensitiv.
Verwenden Sie den $metadata-Endpunkt, um verfügbare Entitäten und Eigenschaften zu inspizieren:
```
GET https://app.inloox.com/api/odata/$metadata
```

Ratenbeschränkungen

Die InLoox API veröffentlicht keine strikten Ratenbeschränkungen, aber folgen Sie diesen Best Practices, um eine Drosselung zu vermeiden:

Lesevorgänge bündeln — Verwenden Sie $filter und $select, um die Anzahl der Anfragen zu minimieren
Nicht aggressiv abfragen — Warten Sie zwischen wiederholten Anfragen mindestens einige Sekunden
Effizient paginieren — Folgen Sie @odata.nextLink statt überlappende Abfragen zu erstellen
Caching verwenden — Speichern Sie Ergebnisse lokal zwischen, wenn sich die Daten nicht häufig ändern

hinweis

Wenn Sie eine 429 Too Many Requests-Antwort erhalten, warten Sie die im Retry-After-Header angegebene Dauer ab, bevor Sie einen neuen Versuch unternehmen.

Nächste Schritte

💻 Sehen Sie sich die Code-Beispiele an, um funktionierende C#-Implementierungen zu erkunden
📂 Lesen Sie die Projekt-Dokumentation, um mit Ihrem ersten Endpunkt zu beginnen
✅ Erfahren Sie mehr über die Aufgaben-API zum Abfragen und Verwalten von Aufgaben
⏱️ Erfahren Sie mehr über die Zeiterfassung, um Zeitdaten programmatisch zu verwalten

Voraussetzungen​

Authentifizierung​

cURL​

C# (HttpClient)​

C# (Simple.OData.Client)​

JavaScript (fetch)​

Basis-URL​

OData-Grundlagen​

Was ist OData?​

$filter — Daten filtern​

$select — Felder auswählen​

$orderby — Sortierung​

$top und $skip — Paging​

$count — Gesamtanzahl​

$expand — Verknüpfte Daten laden​

Abfrageoptionen kombinieren​

Paginierung​

Paginierungsstrategie​

Funktionsweise der Paginierung​

Beispiel: Alle Projekte abrufen (C#)​

Paginierung mit Simple.OData.Client (C#)​

Beispiel: Paginierung mit cURL​

Antwortformat​

Beispielantwort für eine Liste​

Beispielantwort für ein einzelnes Objekt​

Wichtige Felder​

Fehlerbehandlung​

Fehlerantwort-Beispiel​

Ratenbeschränkungen​

Nächste Schritte​