Resolve before you read

Which call answers which question

Three endpoints take a string and none of them answers the same question. Picking the wrong one is the single most common reason an integration shows the wrong firearm.

The reference for both is on the resolve page and the search page. If a reader is choosing, you want search; if your code is choosing, you want resolve.

Resolve many names at once

Extracting the firearms named in a document, a spreadsheet column or a chat message means dozens of names at once. One request per name turns an inline feature into a background job.

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}

• Up to fifty queries in one call, and each result echoes its own query, so nothing has to be matched up by position.
• An unknown name comes back as a result with status: "not_found", never as an error. One bad name does not fail the other forty-nine.
• A batch costs one request against your quota rather than fifty, so it is worth building even where a loop would work.

Treat the score as a decision, not a decoration

Each result carries a status and a score, because a name can be unambiguous, plausible or meaningless and those need three different behaviours. Write the rule once and use it everywhere a name arrives.

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}

Do not silently fall back to search when resolution fails. A top hit presented as an answer is how the wrong firearm reaches a customer. An ambiguous result already carries its candidates, so show them.

Store the id, not the name

A catalog id is the stable thing in this system. Resolving the same name on every page view spends a request to re-derive something that has not changed since last month.

• Resolve once, store the id beside your own record, and call the catalog by id from then on.
• Store version too: it changes when and only when a field we serve changes, so it tells you whether your copy is stale without another lookup. Caching and freshness covers the rest.
• Keep the original string as well. When a record is merged or renamed, the query that produced the id is what lets you re-resolve without asking the user again.

Four habits worth unlearning

Each of these works in a demo and fails in front of a customer.