Unified Pagination & Filtering, eine Form für jede Ergebnismenge
Systeme paginieren auf unvereinbare Weise, manche über die Seitenzahl, manche über einen Cursor, jedes mit eigenen Eigenheiten. Maesn setzt einen limit- und einen page-Parameter vor alle und ergänzt die Filter, mit denen Sie nur das Geänderte abrufen.
Was ist Unified Pagination & Filtering
Die Form der Daten zu normalisieren ist das eine Problem. Die Form der Ergebnismenge zu steuern ist ein eigenes: welche Datensätze zurückkommen, in welcher Reihenfolge, welche herausgefiltert werden und wie viele auf einmal ankommen. Zwei Systeme können ein identisches Rechnungsobjekt liefern und sich trotzdem völlig uneins sein, wie Sie durch zehntausend davon gehen.
Unified Pagination & Filtering ist die Ebene, die das klärt. Ein Blätterschema, ein Satz Filterparameter und ein Weg, Ergebnisse zu sortieren, über jedes System hinweg, die Schleife, die Sie für die erste Anbindung schreiben, ist also die Schleife, die für alle funktioniert. Es steht neben das Common Data Model statt darin: Das Modell klärt, wie ein Datensatz aussieht, dies klärt, welche Datensätze Sie bekommen.
Zwei Paradigmen, und je System eine Variante
Blättern ist nicht ein Problem mit einer Lösung. Es sind zwei unvereinbare Modelle, jedes mit Eigenheiten je System obendrauf, und Sie treffen auf alle, sobald Sie zum ersten Mal eine vollständige Liste lesen wollen.
Sie zählen und fordern nummerierte Seiten an.
- 1Fragen, wie viele Seiten es gibt
- 2Seite 1, 2, 3 in einer Schleife anfordern
- 3Eine Seite früher stoppen, die letzte scheitert
- 4Manche geben die Maximalzahl in der URL
Sie folgen einem Lesezeichen, bis es endet.
- 1Den ersten Stapel anfordern
- 2Den Cursor aus der Antwort lesen
- 3Ihn zurücksenden für den nächsten Stapel
- 4Die Gesamtzahl erfahren Sie nie
Zwei unvereinbare Paradigmen, dazu je System eine Variante. Wer direkt dagegen baut, braucht für jede Anbindung eine eigene Blätterschleife.
Zwei Parameter, vorhersehbare Ergebnisse
Sie senden limit und page. Maesn übersetzt das in das, was das Zielsystem wirklich braucht, und gibt eine gleichbleibende Seite normalisierter Datensätze zurück.
Nimmt 5, 10, 20, 50 oder 100, sodass eine Seitengröße immer ein gültiger, vorhersehbarer Wert ist.
Beginnt bei 1 und zählt hoch, ohne Vorabfrage und ohne Off-by-one am Ende der Menge.
Überall eine Paginierung
Seitenbasierte Schemata, Cursor-Lesezeichen und ihre Varianten je System liegen alle hinter denselben zwei Query-Parametern.
Delta über lastModified
Übergeben Sie den Zeitstempel Ihres letzten Abrufs und erhalten Sie nur die Objekte, die seitdem neu oder geändert sind.
Filter, wo sie zählen
Neben lastModified gibt es status auf Rechnungen, dazu Filter für die Lücken eines bestimmten Systems, auf denselben vereinheitlichten Endpunkten.
Sortierung, die Sie steuern
Sortieren Sie Rechnungen, Eingangsrechnungen und Buchungsvorschläge nach Datum, Nummer oder Erstell- und Änderungszeitstempel, aufsteigend oder absteigend.
const res = await axios.get(url, {params: { limit: 50, page: 1 },headers: {'X-API-KEY': apiKey,'X-ACCOUNT-KEY': accountKey}});
Sie erfahren auch die Größe
Jede Antwort trägt meta.pagination als eigenen Block. Genau das kann ein Cursor nicht: eine Zahl anzeigen, die Arbeit planen und wissen, wann Sie fertig sind, auf Systemen, die selbst nie eine Gesamtzahl herausgeben.
Holen Sie das Geänderte, nicht wieder alles
Der Filter, von dem die meisten Anbindungen am Ende leben, ist lastModified. Sie merken sich den Zeitstempel Ihres letzten erfolgreichen Abrufs, übergeben ihn bei der nächsten Anfrage und erhalten nur die Objekte, die seitdem neu oder geändert sind. Aus einem nächtlichen Abgleich über das ganze Hauptbuch eines Kunden wird eine Anfrage, die eine Handvoll Datensätze liefert.
Er ist auf fast jedem Schema und Endpunkt eingebaut, und das macht ihn als allgemeine Strategie brauchbar statt als Sonderfall. Die praktische Regel dazu: so selten abfragen, wie Ihre Daten noch frisch genug bleiben. Jede Minute nach etwas zu fragen, das sich einmal am Tag ändert, ist verschenkter Verkehr und verschenktes Geld, und das Budget, das Sie ausgeben, ist das des Zielsystems. Maesn setzt auf dem Hinweg kein eigenes Rate-Limit, bei einem gewöhnlichen synchronen Aufruf ist also das Limit des Systems das, was Sie aufbrauchen können, und eine Abweisung erreicht Sie als eigener standardisierter Fehler statt als allgemeiner Fehlschlag. Asynchronous Processing gibt Volumen in dem Tempo frei, das das System annimmt, auf den Endpunkten, die es unterstützen, und das ist eine engere Menge als jeder Aufruf, den Sie machen. Wo Sie im Moment der Änderung reagieren müssen statt nach Zeitplan, pushen Unified Webhooks Ihnen das Event stattdessen zu, und viele Anbindungen fahren beides: Webhooks für die Unmittelbarkeit, einen regelmäßigen Delta-Abruf als Netz.
Illustrativ. Graue Objekte lagen schon in Ihrer Datenbank.
Sie bekommen die zwei Objekte, die seit Ihrem Zeitstempel neu oder geändert sind, nicht wieder das ganze Hauptbuch.
Filter gebaut für das, was jedem System fehlt
Manche Filter gibt es überall, andere gibt es, weil ein System eine Lücke hat, die zu schließen sich lohnt. Beide liegen auf denselben vereinheitlichten Endpunkten, sie zu nutzen kostet Sie also keinen Code je System.
sevdesk
·KontakteKontakte über ihre Kontaktnummer suchen, Kunden und Lieferanten im selben Filter.
sevdesk anbindenLexware Office
·KontakteKontakte nach Name oder E-Mail-Adresse filtern, um einen schon vorhandenen Datensatz zuzuordnen.
Lexware Office anbindenSage Active
·RechnungenSage Active kennt im regulären Rechnungsstatus kein bezahlt oder teilbezahlt, deshalb ist der Zahlungsstatus ein eigener Filter.
Sage Active anbindenBuchhaltungsButler
·EingangsrechnungenNur Eingangsrechnungen zurückgeben, deren Belegdatum nach dem übergebenen Wert liegt, gefiltert in der Anfrage selbst.
BuchhaltungsButler anbindenNicht jede Ressource unterstützt alle drei, Filtern, Sortieren und Paginieren, und Maesn behauptet nichts anderes. Die Fähigkeit muss irgendwo darunter vorhanden sein, die Unterstützung ist deshalb je Endpunkt in der API-Referenz dokumentiert. Sie sehen, was ein Endpunkt bietet, bevor Sie dagegen bauen, und genau das kann eine vereinheitlichende Ebene sein: einheitlich, wo Einheitlichkeit möglich ist, und offen an den Rändern.
Eine Schleife, jedes System
- Je System eine Blätterschleife schreiben
- Cursor und Seitenzahlen behandeln
- Die scheiternde letzte Seite umgehen
- Alles neu holen, um Änderungen zu finden
- Überall ein limit und ein page
- Cursor und Zählung für Sie erledigt
- Kein Off-by-one zu umgehen
- Nur das seither Geänderte holen
Eine vollständige Liste zu lesen klingt nach dem Einfachsten, was eine Anbindung tut, und dort verschwindet erstaunlich viel Zeit: eine Blätterschleife je System, ein Umweg um die Seite, die scheitert, und jede Nacht ein vollständiges Neulesen, weil es keinen verlässlichen Weg gibt, nach dem Geänderten zu fragen. Weil Sie über Maesn blättern und filtern statt gegen jedes System, passiert diese Arbeit einmal. Dieselben zwei Parameter und derselbe Delta-Filter tragen über jede Anbindung, die Sie ergänzen, auch die, die Maesn nach Ihrem Livegang ergänzt, und der Kunde braucht sich dafür nur sich einmal zu verbinden. Die Blätterschleife, die niemand noch einmal schreibt, ist Zeit, die Produkt- und Entwicklungsteams bei jeder Anbindung nach der ersten zurückbekommen.
Häufige Fragen
Wie funktioniert die Paginierung in der Maesn API?
Muss ich wissen, ob ein System Cursor oder Seitenzahlen nutzt?
Erfahre ich, wie viele Datensätze es gibt?
Wie hole ich nur die geänderten Datensätze?
Welche Filter gibt es neben lastModified?
Kann ich die Reihenfolge der Ergebnisse steuern?
Unterstützt jede Ressource Filtern, Sortieren und Paginieren?
Wie oft sollte ich abfragen?
Sollte ich abfragen oder Webhooks nutzen?
Einmal bauen, auf der Unified API.
Sehen Sie, wie Unified Pagination & Filtering für Ihre Integration funktioniert, oder steigen Sie in die technische Referenz ein.