Praxis
Die richtigen Datensätze finden
Die meisten "Wie frage ich X ab"-Fragen sind ein Aufruf mit den richtigen Parametern. Hier steht die Zuordnung, dazu die zwei Regeln, die sie günstig halten.
Frage zu Endpunkt: suchen, filtern, blättern
Jede Zeile hier ist eine Anfrage: nach Patrone suchen, nach Hersteller oder Land filtern, eine Kategorie durchblättern. Die Variante, die man zuerst schreibt (alles listen, im eigenen Code filtern), ist dieselbe Antwort zum Hundertfachen des Kontingents.
| Was Sie wollen | Der Aufruf | Hinweise |
|---|---|---|
| 9-mm-Pistolen aus Österreich, noch in Produktion | GET /v1/firearms?caliber=&category=&country_of_origin=&status= | Filter kombinieren und werden in der Datenbank angewendet. Sortierung über sort und order. |
| Alles in einer Patrone | GET /v1/calibers/{id}/firearms | Die Sicht von der Patrone aus, bereits paginiert. |
| Alles eines Herstellers | GET /v1/manufacturers/{id}/firearms | Dieselbe Form für eine Markenseite. |
| Alles in einer Kategorie | GET /v1/categories/{slug}/firearms | Kategorien ohne Waffen werden gar nicht erst gelistet. |
| Datensätze mit einem Merkmal (Gewinde, M-LOK) | GET /v1/firearms/by-feature?feature= | Merkmals-Slugs kommen aus filter-options; by-action, by-material, by-designer und by-conflict funktionieren gleich. |
| Was ein Land führt, nach Nutzerart | GET /v1/countries/{code}/arsenal | Gruppiert nach Militär, Polizei und so weiter. |
| Eine sortierte Seite zur Auswahl durch Menschen | GET /v1/firearms/search?q= | Volltext über Namen und Beschreibungen. Eine Rangfolge, keine Entscheidung. |
| Welcher Datensatz ein getippter Name ist | GET /v1/firearms/resolve?q= | Eine ID und ein Status. Dieser Aufruf gehört vor das Laden eines Datensatzes. |
| Die Varianten eines Modells | GET /v1/firearms/{id}/variants | Direkte Kinder. Der Stammbaum-Endpunkt geht weiter. |
| "Das könnte Ihnen auch gefallen" | GET /v1/firearms/{id}/similar | Zehn Datensätze, bewertet nach Kaliber, Hersteller, Verschluss, Größe und Jahr; Bilder inline. |
| Spitzenreiter bei einem messbaren Wert | GET /v1/firearms/top?stat= | Datensätze ohne die Messung werden ausgeschlossen statt als Null geführt. |
| Was Leute tatsächlich ansehen | GET /v1/popular/firearms?days= | Aufrufaktivität über ein gleitendes Fenster, für eine Startseiten-Leiste. |
Serverseitig filtern
Jeder Parameter auf dem Listen-Endpunkt verengt die Abfrage, bevor die Seite gebaut wird, sodass ein enger Filter eine Anfrage kostet und eine Seite liefert. Die vollständige Parameterliste steht dort; hier zählt, dass sie sich kombinieren lassen.
filters.sh
bash
# Filters combine, and they are applied in the database.# 9mm semi-automatic pistols still in production, made in Austria,# newest first, a hundred to a page.curl -sS -H "X-API-Key: $GUNSPEC_API_KEY" \ "https://api.gunspec.io/v1/firearms?caliber=9x19mm-parabellum&category=pistol\&country_of_origin=AT&status=in_production&sort=year&order=desc&per_page=100" # Only records that have a photograph or a render, for a page that# is mostly pictures.curl -sS -H "X-API-Key: $GUNSPEC_API_KEY" \ "https://api.gunspec.io/v1/firearms?category=rifle&has_image=true&per_page=24"- Eine gefilterte Anfrage schlägt Durchlauf plus Schleife. Den ganzen Katalog zu paginieren, um elf Gewehre zu finden, ist der teuerste Weg zu einer billigen Frage, und im Tarif sieht man es.
- Bereiche sind Paare:
weight_min/weight_max,year_introduced_min/year_introduced_max, in den Einheiten, die die Feldnamen tragen. fieldskürzt die Antwort auf das, was Sie rendern. Eine Listenseite mit Name, Jahr und Bild braucht keine siebzig Felder je Zeile.- Sortieren Sie bewusst.
sort=created_at&order=ascist die stabile Reihenfolge für einen Durchlauf;nameist die, die sich verschiebt, sobald ein Datensatz hinzukommt.
Das Vokabular von der API holen
Ein Aufruf liefert jeden Wert, hinter dem aktuell Datensätze stehen, also genau das, was eine Filter-UI anbieten sollte. Fest verdrahtete Listen sind der Grund, warum ein Dropdown tote Optionen zeigt und die Kategorie von letztem Monat übersieht.
filter-options.ts
javascript
// Build the filter UI from the API, not from a constant.// Categories, manufacturers and calibers nothing uses are left out,// so an option in this list always returns results.const { data } = await gunspec.firearms.filterOptions() // data.manufacturers, data.categories, data.calibers,// data.actionTypes, data.features. Countries come from// /v1/countries, which carries the names and codes.//// Hardcoding these is how a UI ends up offering "Flintlock" with// nothing behind it, and missing the category added last month.Autocomplete sind zwei Endpunkte
Die Suche sortiert während des Tippens, resolve entscheidet bei der Auswahl. Beides mit der Suche zu erledigen bringt die falsche Waffe auf die Seite, wie Erst auflösen, dann lesen darlegt.
autocomplete.ts
javascript
// An autocomplete has two jobs and they are two endpoints.// While the user types: rank plausible records for them to pick.const { data: suggestions } = await gunspec.firearms.search({ q: typed, per_page: 8 }) // Once they pick, or paste a name and hit enter, decide which// record it is and act on the status rather than the ranking.const { data } = await gunspec.firearms.resolve(typed)if (data.status === 'resolved') go(data.firearmId)- Entprellen Sie die Tastendrücke. Eine Anfrage pro Zeichen ist ein selbst bestelltes Limit.
- Cachen Sie die Vorschlagsliste je Suchstring für einige Minuten: Menschen tippen den ganzen Tag dieselben Präfixe.
- Die Suche braucht Builder oder höher. Auf Explorer treiben Sie das Feld über
filter-optionsund die Listenfilter.
Alle Patronen, Hersteller, Kategorien oder Länder listen
Die Referenzlisten sind eigene Endpunkte, alle gleich paginiert und günstig genug, um sie einmal zu holen und einen Tag zu cachen.
GET /v1/calibers,/v1/manufacturers,/v1/categories,/v1/countriesund/v1/ammunitionsind die Kataloge hinter den Filtern.- Erhöhen Sie
per_page, statt zu durchlaufen: diese Listen sind Hunderte Zeilen, keine Tausenden, also reichen ein bis zwei Anfragen. Paginierung nennt die Grenzen. - Cachen Sie sie einen Tag. Eine Patronenliste ändert sich, wenn der Katalog eine Patrone gewinnt, nicht je Anfrage und nicht je Nutzer.
- Für eine Filter-UI besser
/v1/firearms/filter-options: es liefert nur Werte, hinter denen aktuell Datensätze stehen.
Vergleichen, Varianten, Stammbäume und Ähnliches
Mehrere Fragen, die wie Joins aussehen, sind eigene Endpunkte und liefern die Datensätze fertig zusammengesetzt.
/v1/firearms/{id}/family-treegeht in beide Richtungen;/variantssind nur die Kinder./v1/firearms/{id}/usersist, wer sie führt, und/adoption-mapdasselbe als Geografie./v1/firearms/{id}/attachmentsist, was passt, mit eigenen Regeln. Siehe Was passt worauf./v1/firearms/comparenimmt bis zu fünf IDs und liefert sie ausgerichtet: eine Anfrage statt fünfget-Aufrufen.