Erst auflösen, dann lesen

Welcher Aufruf welche Frage beantwortet

Drei Endpunkte nehmen eine Zeichenkette entgegen, und keiner beantwortet dieselbe Frage. Der falsche ist der häufigste Grund dafür, dass eine Integration die falsche Waffe zeigt.

Die Referenz zu beiden steht auf der Resolve-Seite und der Suchseite. Wählt ein Mensch, nehmen Sie die Suche; wählt Ihr Code, nehmen Sie resolve.

Viele Namen auf einmal auflösen

Die Waffen aus einem Dokument, einer Tabellenspalte oder einer Nachricht zu ziehen heißt: Dutzende Namen gleichzeitig. Eine Anfrage pro Name macht aus einer sofortigen Funktion einen Hintergrundjob.

1// Fifty names, one round trip. Each result echoes its own query,2// so nothing has to be matched up by position.3const res = await fetch('https://api.gunspec.io/v1/firearms/resolve', {4  method: 'POST',5  headers: {6    'X-API-Key': process.env.GUNSPEC_API_KEY,7    'Content-Type': 'application/json',8  },9  body: JSON.stringify({10    queries: ['G19 gen 5 MOS', 'AK-47', 'H&K MP5', 'that one from Die Hard'],11  }),12})13 14const { data } = await res.json()15for (const result of data.results) {16  // An unknown name is a result with a status, not an error: one17  // bad name in fifty does not fail the batch.18  if (result.status !== 'resolved') {19    review.push(result)20    continue21  }22  resolved.set(result.query, result.firearmId)23}

• Bis zu fünfzig Anfragen in einem Aufruf, und jedes Ergebnis wiederholt seine eigene query. Nichts muss über die Position zugeordnet werden.
• Ein unbekannter Name kommt als Ergebnis mit status: "not_found" zurück, nie als Fehler. Ein schlechter Name lässt die anderen neunundvierzig nicht scheitern.
• Ein Batch kostet eine Anfrage vom Kontingent statt fünfzig. Deshalb lohnt er sich auch dort, wo eine Schleife möglich wäre.

Der Score ist eine Entscheidung, keine Zierde

Jedes Ergebnis trägt Status und Score, weil ein Name eindeutig, plausibel oder bedeutungslos sein kann: drei Fälle, drei Verhaltensweisen. Schreiben Sie die Regel einmal und nutzen Sie sie überall dort, wo ein Name ankommt.

1// One decision, written once, used everywhere a name arrives.2function decide(result) {3  switch (result.status) {4    case 'resolved':5      // Certain enough to act on unattended. Below that, the answer6      // is probably right, which is not the same thing.7      return result.score >= 0.98        ? { action: 'use', id: result.firearmId }9        : { action: 'confirm', id: result.firearmId, from: result.query }10 11    case 'ambiguous':12      // Several records fit equally well and the API deliberately13      // did not choose. Offer `alternatives`; do not pick [0].14      return { action: 'choose', options: result.alternatives }15 16    default:17      // Nothing matched. `unresolvedTokens` names the words that18      // carried no meaning, which is what to show the user.19      return { action: 'ask', unresolved: result.unresolvedTokens }20  }21}

Fallen Sie nicht stillschweigend auf die Suche zurück. Ein erster Treffer, als Antwort präsentiert, ist der Weg, auf dem die falsche Waffe beim Kunden landet. Ein mehrdeutiges Ergebnis trägt seine Kandidaten bereits, also zeigen Sie sie.

Speichern Sie die ID, nicht den Namen

Die Katalog-ID ist das Stabile in diesem System. Denselben Namen bei jedem Seitenaufruf aufzulösen kostet eine Anfrage, um etwas neu herzuleiten, das sich seit letztem Monat nicht geändert hat.

• Einmal auflösen, die ID neben Ihrem eigenen Datensatz speichern und den Katalog fortan über die ID ansprechen.
• Speichern Sie auch version: sie ändert sich genau dann, wenn sich ein ausgeliefertes Feld ändert, und sagt ohne weiteren Aufruf, ob Ihre Kopie veraltet ist. Caching und Aktualisierung erklärt den Rest.
• Behalten Sie die ursprüngliche Zeichenkette. Wird ein Datensatz zusammengeführt oder umbenannt, führt die Anfrage, die zur ID geführt hat, zurück, ohne die Nutzer erneut zu fragen.

Vier Gewohnheiten, die man ablegen sollte

Jede funktioniert in der Demo und scheitert vor dem Kunden.