lcbo api

Hallo, willkommen bei der LCBO API?

Wenn Sie sich hier fragen: „Was ist eine LCBO-API?“, lassen Sie es mich erklären. In Ontario, Kanada, laufen alle Getränkeverkäufe von Alkohol über ein staatliches Unternehmen namens Liquor Control Board of Ontario (LCBO), das den Einzelhandel und Vertrieb alkoholischer Getränke in der gesamten Provinz verwaltet. Das LCBO verfügt über zahlreiche Einzelhandelsgeschäfte und eine Website, auf der ein Katalog aller Produkte, Geschäfte und sogar der Lagerbestände gehostet wird. Sie veröffentlichen einen saisonalen Katalog mit Rezepten, Leitartikeln und anderen Inhalten mit dem Titel „Food & Drink“. Sie tragen außerdem jedes Jahr Einnahmen in Milliardenhöhe zu unserem öffentlichen Gesundheitssystem bei. Es ist eine faszinierende Situation, wenn man darüber nachdenkt, andere Orte haben ähnliche Systeme, aber meines Wissens hat keines die Breite und Tiefe des LCBO. So, jetzt wissen Sie, was es ist, ziemlich cool, oder?

Dies könnte für Sie auch dann interessant sein, wenn Sie nicht in Ontario, Kanada, leben, wenn:

• Sie möchten Zugriff auf viele Daten zum Lernen oder Testen haben
• Sie möchten gerne erfahren, wie einige Arten von Webcrawlern funktionieren
• Sie möchten gerne erfahren, wie eine Rails-Produktionsanwendung aussehen könnte, die sich über 10 Jahre Entwicklungszeit erstreckt

Ein wichtiger Hinweis?

Im gesamten Verlauf dieses Projekts hatte ich große Probleme mit dem Gedanken, finanzielle Unterstützung anzunehmen. Einerseits brauchte LCBO API es, andererseits war ich der Komplikationen überdrüssig, die es verursachen würde. Nun, jetzt habe ich DIE PERFEKTE Lösung für dieses Problem!

Ich werde gerade wegen Blutkrebs behandelt, insbesondere wegen des diffusen großzelligen B-Zell-Lymphoms. Ich werde bald woanders mehr darüber schreiben, aber im vergangenen Jahr haben mich Menschen von überall auf jede erdenkliche Weise unterstützt, und es hat mich verändert. Ich möchte, dass wir etwas Großes tun, um zu zeigen, dass wir uns auch darum kümmern!

Wenn Sie dieses Projekt in der Vergangenheit jemals unterstützen wollten, spenden Sie bitte im Namen von LCBO API eine Spende an Hamilton Health Sciences, sie retten mein Leben.

Spenden Sie an Hamilton Health Sciences

Ich werde im Juravinski-Krebszentrum behandelt, aber Sie können wirklich jede Option wählen oder die Standardoption belassen. Es spielt keine Rolle, ob der Betrag klein oder groß ist, ich werde benachrichtigt, wenn Sie spenden. Ich werde eine Liste erstellen, um die Gesamtsumme zu verfolgen. Mal sehen, wie viel wir sammeln können!

Abschließend möchte ich meinen Arbeitsplatz Crowdmark besonders erwähnen. Sie waren während all dem unglaublich freundlich und verständnisvoll, und ohne sie hätte ich das im wahrsten Sinne des Wortes nicht geschafft. Wir arbeiten unermüdlich daran, den Status quo der Beurteilung in der Hochschulbildung voranzutreiben. Wenn Ihnen Bildung und Lernen am Herzen liegen, empfehle ich Ihnen dringend, bei uns vorbeizuschauen.

Hintergrund

Im Herbst 2008 war ich ein frischgebackener Webentwickler mit einigen Jahren Erfahrung. Ich war hungrig nach einer Herausforderung und nach Anerkennung. Apps wurden damals immer beliebter und ich wollte unbedingt eine entwickeln. Ich beschloss, eine zu erstellen, bei der ich zuerst diese API erstellen musste. Ich habe diese App nie erstellt?

Freundlich sein

Wenn Sie sich lange genug mit dieser Codebasis befassen, werden Sie wahrscheinlich Momente der Frustration, Sackgassen, verwirrendes Durcheinander usw. finden. Ich hoffe wirklich, dass Sie sich nicht darauf oder auf irgendwelche Negativität, die Sie finden, konzentrieren. Ich bin nicht mehr diese Person und ich möchte auch nicht, dass du diese Person bist. Ich bin diesbezüglich ein offenes Buch! Eröffnen Sie ein Problem und stellen Sie mir eine Frage. Ich werde so ehrlich und respektvoll wie möglich sein und Sie nur bitten, dasselbe zu tun.

Lizenz

Ich veröffentliche dieses Projekt unter GNU GPLv3. Ich denke, das ist die fairste und verantwortungsvollste Option für ein Projekt wie dieses. Wenn Sie anderer Meinung sind, eröffnen Sie ein Problem und wir können eine offene Diskussion darüber führen. Ich bitte Sie nur respektvoll darum, das Branding und Design nicht wiederzuverwenden. Ich bin mit der Wiederverwendung der Dokumentation einverstanden, aber Stil, Identität und Branding müssen geändert werden, wenn Sie Ihre eigene isolierte Version dieser App bereitstellen möchten.

Habe große Träume!

Was wäre, wenn wir statt einer monolithischen Anwendung, die versucht, alles in einem Stil und an einem Ort zu erledigen, größer denken würden? Was wäre, wenn der Crawler wieder ein separates Projekt wäre, das für das Sammeln und Normalisieren von Daten verantwortlich wäre, andere könnten API-Knoten auf beliebigen Plattformen erstellen, diese Knoten würden sich beim Datenanbieter registrieren und aktualisierte Daten erhalten, sobald sie verfügbar sind, und diese Daten bereitstellen Benutzer aller Art.

Anstatt dass Dutzende ähnlicher API-Server versuchen, dasselbe zu tun und um die Ressourcen von LCBO.com zu kämpfen, könnten wir unsere Bemühungen auf die Wertschöpfung dieser Daten konzentrieren, anstatt um den Besitz dieser Daten zu kämpfen. Wir könnten andere Disziplinen einbeziehen, um neue Werte zu schaffen, die über das Offensichtliche hinausgehen, die Craft-Beer- und Wein-Communitys einbeziehen, darauf aufbauen und es größer machen als nur Ontario.

Ich weiß nicht, wie machbar so etwas wäre, aber ich weiß, wenn andere interessiert sind, würde ich diese Diskussionen gerne führen.

Vielleicht sollten wir auch darüber nachdenken, Unternehmensbenutzern eine angemessene Gebühr für den Zugriff auf die API-Knoten zu berechnen, dieses Geld könnte zur Finanzierung der Hosting-Kosten verwendet werden, um die Dinge nachhaltig zu halten, es könnte auch zur Finanzierung von Unterstützungsprogrammen für Menschen verwendet werden, die nicht trinken können, oder die nicht oder weniger trinken wollen, um unseren Gemeinschaften etwas zurückzugeben und tatsächlich etwas zu bewirken.

Aber ich brauche andere, die mir helfen, die Last zu tragen, all das aufrechtzuerhalten und zu verwalten. Die Gesundheit und das Glück von mir und meiner Familie haben oberste Priorität, gefolgt von meiner Karriere und dann meinen Freunden und meiner Gemeinschaft. Dieses Projekt kann nicht mehr mein größter Zeitfresser sein, es ist für mich nicht nachhaltig und nicht gesund für mich. Wenn Sie sich jedoch von dieser Nachricht inspirieren lassen, wenden Sie sich bitte an mich, am besten offen, aber auch zunächst privat ist in Ordnung.

Ich hoffe, das begeistert Sie!

Ich konnte nicht anders und habe mehr über meine Ideen dazu geschrieben: doc/lcboapi-proposed.md

Erste Schritte

Nachdem das nun geklärt ist, können wir uns damit befassen, für wen ich das wirklich getan habe und was mich überhaupt begeistert und inspiriert hat, dies zu tun: die Gelegenheit, zu lernen und zu wachsen und anderen dabei zu helfen, das Gleiche zu tun. Für diejenigen unter Ihnen, die neugierig sind: Mal sehen, wohin das führt?

Führen Sie die Rails-App aus?

Sie können die App wahrscheinlich direkt auf Ihrer Host-Umgebung ausführen, es sind keine allzu komplizierten Systemabhängigkeiten erforderlich. Ich entwickle auf Apple-Hardware. Wenn Sie dies auch tun, haben Sie möglicherweise Erfolg, wenn Sie Postgres.app und Homebrew für die Installation von Redis verwenden. Ansonsten können Sie Docker verwenden.

Wenn Sie Erfahrung mit einer anderen Plattform haben, machen Sie bitte eine PR oder ein Problem und wir können daran arbeiten, Ihre Plattform zur README-Datei hinzuzufügen.

Wenn das, was hier folgt, für Sie keinen Sinn ergibt, öffnen Sie ein Problem. Vielleicht könnten wir einen Screencast machen, um den Prozess zu demonstrieren, oder vielleicht würde jemand da draußen, der gut darin ist, das übernehmen?

Was ich unten beschreibe, ist nur eine Möglichkeit, eine Entwicklungsumgebung einzurichten, um die LCBO-API auf Ihrem Computer auszuführen. Wenn andere Verbesserungen haben (es gibt Platz für viele, zum Beispiel ein Einstiegsskript zum Bootstrap der Entwicklungsdatenbank) oder sogar andere Ansätze, wie die Verwendung von Vagrant + VirtualBox, das Öffnen eines Problems oder eine PR, füge ich sie gerne hinzu.

Wenn Sie helfen möchten, möchte ich es Ihnen ermöglichen.

Erste Schritte

Einrichten config/secrets.yml und .env

Zunächst müssen Sie einige Konfigurationen einrichten, die nicht im öffentlichen Repository bereitgestellt werden. Der Grund dafür ist der Schutz privater Daten wie API-Schlüssel und geheimer Token, aber auch, weil einige Entwickler aufgrund ihrer persönlichen Vorlieben und dergleichen möglicherweise etwas andere Einstellungen bevorzugen.

Es gibt ein paar Dateien, die Sie erstellen müssen: config/secrets.yml und .env . Es gibt Vorlagenversionen im Repo unter config/secrets.yml.example und .env.example . Sie können diese Dateien kopieren, um loszulegen:

 cp config/secrets.yml.example config/secrets.yml
cp .env.example .env

Wenn Sie die App nur starten und lokal darauf zugreifen möchten, sollten Sie an dieser Stelle bereit sein. Wenn Sie den Crawler verwenden und einen in Amazon S3 gespeicherten Snapshot speichern möchten, müssen Sie Ihre AWS-Anmeldeinformationen und Ihren Bucket zu config/secrets.yml hinzufügen.

Die restlichen Einstellungen sind entweder nur in einer Produktionsumgebung wirklich wichtig, werden nicht wirklich verwendet oder sind nur wichtig, wenn Ihnen die Standardeinstellung nicht gefällt. Wie immer gilt: Wenn Sie eine Klarstellung benötigen, öffnen Sie uns und stellen Sie ein Problem. Ich helfe Ihnen gerne weiter.

Die App zum ersten Mal ausführen

Zuerst müssen Sie den Docker-Client für Ihr System installieren, mehr darüber erfahren Sie hier. Sobald Sie Docker installiert haben, können Sie loslegen:

Als nächstes müssen Sie die Container erstellen:

 docker-compose build

Wenn das erledigt ist, können Sie das Ganze starten, indem Sie Folgendes eingeben:

 docker-compose up

Zu diesem Zeitpunkt sind noch keine Daten in der Datenbank vorhanden. Wenn Sie also die App http://localhost:3000 laden, wird das nicht viel bewirken, denn schließlich werden Daten bereitgestellt, und die App enthält keine Daten. Also lasst uns etwas dagegen unternehmen.

Fahren Sie fort und schließen Sie die Container:

 Ctrl-C

Das heißt, drücken Sie gleichzeitig die Tasten Control + C

Sie können hier ein Archiv des neuesten Produktionsdatenbank-Dumps von meinem persönlichen Amazon S3-Konto herunterladen. Bitte beachten Sie, dass es sensible Tabellen (E-Mails, Benutzer, Schlüssel) gibt und dass Daten aus dieser Datei ausgeschlossen wurden.

Laden Sie das Archiv herunter und extrahieren Sie es im tmp -Verzeichnis dieses Projekts:

 cd tmp
curl -O https://heycarsten.s3.amazonaws.com/lcboapi-2019-01-21.tgz
tar xzf lcboapi-2019-01-21.tgz
cd ..

Die Datei ist etwa 300 MB groß, daher kann der Download je nach Verbindungsgeschwindigkeit eine Weile dauern (dies geschieht in der Zeile, die mit curl beginnt).

Nachdem Sie die Datenbankdatei heruntergeladen und extrahiert haben, können Sie die Daten in die Datenbank laden:

 docker-compose run --rm app rake db:create
docker-compose run --rm app bash -c 'pv tmp/lcboapi-2019-01-21.sql | psql -q -h db -U $POSTGRES_USER $POSTGRES_DB > /dev/null'

Die erste Zeile, die mit rake db:create endet, erstellt die Datenbankschemata in Postgres für Entwicklung und Tests, die zweite Zeile lädt den Datenbank-Dump in die Entwicklungsdatenbank. Der Fortschrittsbalken zeigt an, wie viele Daten in die Datenbank weitergeleitet wurden. Sobald dies abgeschlossen ist, werden Indizes erstellt. Dies kann je nach Computer einige Zeit dauern, da es sich um eine beträchtliche Datenmenge handelt. Anschließend können Sie die App erneut starten:

 docker-compose up

Sie können an dieser Stelle auch das Archiv und die extrahierte SQL-Datei sicher aus Ihrem tmp -Verzeichnis löschen.

Wenn Sie das Eintippen docker-compose immer wieder als mühsam empfinden, schauen Sie sich die Shell-Aliase an

Sie können Ihrem Shell-Profil eine Alias-Zeile wie alias dc=docker-compose hinzufügen und dann einfach dc eingeben, anstatt jedes Mal docker-compose eingeben zu müssen. ✅

Denken Sie an andere Aliase, die Sie erstellen könnten, um dies noch weiter zu verbessern?

Navigieren Sie nun zu http://localhost:3000/products/438457

Boom. Auf Ihrem Computer läuft die LCBO-API! ? ? ?

Führen Sie die App von nun an aus

Wenn Sie mit der Arbeit an der App fertig sind, drücken Sie einfach Ctrl+C um alles herunterzufahren. Wenn Sie das nächste Mal erneut daran arbeiten möchten, führen Sie docker-compose up aus und schon kann es losgehen!

Neuaufbau (Bundle-Installation)

Wenn Sie der Gemfile ein neues Gem hinzufügen, müssen Sie die Pakete neu installieren und die Abhängigkeiten aktualisieren. Docker kann das ziemlich gut, es kann erkennen, wenn sich Gemfile ändert, und es weiß, dass es den app Container für Sie neu erstellen muss.

Öffnen einer Rails-Konsole

So starten Sie eine Rails-Konsole und prüfen Objekte innerhalb der Anwendung:

 docker-compose exec app rails c

Sobald das läuft, können Sie Dinge tun wie:

Rufen Sie das erste Produkt in der Datenbank ab:

 Product.first

Finden Sie das LCBO-Einzelhandelsgeschäft Nr. 25 (mein lokales Geschäft):

 Store.find(25)

Wenn Sie den Code in der App ändern, müssen Sie das reload! Befehl in der Konsole, um die Änderungen zu aktualisieren.

Laufende Tests

Im spec -Ordner finden Sie die Testsuite für die LCBO-API. Leider ist es nicht umfassend, aber auch nicht schlecht. Ich habe während meiner gesamten Karriere darum gekämpft, Testsuiten zu pflegen, mit denen ich zufrieden bin. Wir sollten diese Tests verbessern!

So führen Sie die Testsuite aus:

 docker-compose exec app rspec

Sie werden eine Reihe grüner Punkte sehen . , jeder davon stellt einen bestandenen Testfall dar. Das ist gut. Wenn ein Fehler auftritt, sehen Sie ein rotes F , das ist schlecht ... nur ein Scherz! Eigentlich ist es gut! Tests geben Ihnen die Möglichkeit, Dinge in einer vorhandenen Codebasis zu ändern und zu sehen, ob dies zu Regressionen bei der vorhandenen Funktionalität führt. Natürlich ist nichts perfekt, aber ich kann Ihnen ohne Zweifel sagen, dass Tests aus Erfahrung gut sind.

Da Anwendungen immer größer und komplexer werden, wird das Fehlen von Tests zu einem wahren Albtraum und macht das Ändern Ihrer Anwendung und das Hinzufügen von Funktionen zu einem äußerst heiklen Prozess. Dinge wie die Verwendung von Sprachen mit Typsystemen und anderen verschiedenen Programmierparadigmen können dabei ebenfalls viel helfen, aber ich bin der Meinung, dass es wirklich keinen Ersatz für zumindest eine solide Akzeptanztestsuite gibt.

Crawler

Dies ist der Teil der LCBO-API, der das Ganze irgendwie möglich macht. Crawler für komplizierte Websites sind schwer zu erstellen und zu warten. Die erste Version der LCBO-API verfügte über eine vollständige Testsuite für den Crawler. Als sich vor vielen Jahren alles änderte, gab ich diese Codebasis auf und baute einfach etwas so schnell wie möglich in dieser Version auf.

Die Crawler-Logik befindet sich in lib/crawler.rb . Von dort aus sehen Sie alle verschiedenen Aufgaben, die nacheinander ausgeführt werden, um ein vollständiges Crawlen der LCBO-Websites zu ermöglichen.

Die Parser-Logik befindet sich in lib/lcbo.rb und allen verschiedenen Dateien in lib/lcbo/* . Dazu gehören alle verschiedenen Anforderungen, die ausgeführt werden müssen, sowie der Code, der für die Umwandlung der Daten aus diesen Anforderungen in strukturierte Daten verantwortlich ist Das kann letztendlich in die Datenbank aufgenommen werden.

Höflich kriechen

Ich habe den Crawler so konzipiert, dass er Anfragen seriell ausführt. Dies ist ein sehr guter Ansatz, wenn Sie eine Website crawlen. Es ist einfach für jemanden, der immer den besten Weg wählt, wenn man kann, und es ist höflich. Wir könnten n AWS Lambda-Jobs starten und jede Seite auf LCBO.com in ein paar Sekunden crawlen, aber das wäre unhöflich, und wir würden ihre Website wahrscheinlich vorübergehend per DDoS attackieren, was nicht gut ist.

Manager-App ( /manager )

Dies umfasst eine Ember-Anwendung. Wenn Sie sich bei der LCBO-API anmelden bzw. anmelden und API-Schlüssel generieren, interagieren Sie damit. Es ist ziemlich veraltet, ich habe noch nicht versucht, es zu bauen. Ich benutze Ember seit dem ersten Tag. Wenn Sie also Fragen dazu haben, melden Sie sich bitte. Es würde mir wirklich Spaß machen, diesen Teil der LCBO-API zu besprechen und mit Ihnen allen zusammenzuarbeiten, um ihn zu verbessern.

Statische Site ( /static )

Dies enthält eine Middleman-Site. Wenn Sie lcboapi.com besuchen, ist dies das, was Sie sehen. Es enthält auch eine sehr kleine (ebenfalls veraltete) React-App, das „Probieren Sie es aus“-Ding rechts auf der Homepage. Es verfügt über eine eigene Gemfile-Datei und ein eigenes Build-Skript static/generate . Wenn dieses ausgeführt wird, wird die Site erstellt und die Änderungen im public Ordner synchronisiert. In Rails-Apps wird der public Ordner als statischer Inhalt bereitgestellt.

Sackgassen

Es gibt VIELE Sackgassen in dieser Codebasis, Zweige, die 40-60-80 % des Weges zu einem Feature zurückgelegt haben und dann stagnierten, Experimente usw. Wie immer, wenn Sie etwas finden, das Ihnen gefällt? Reichen Sie einfach ein Problem ein und ich werde so schnell wie möglich antworten.

Es wäre auch cool, wenn wir hier einige der Sackgassen schließen könnten. Ich wäre sehr daran interessiert, endlich JSON:API und GraphQL hinzuzufügen. Das aktuelle API-Antwortdesign stammt aus dem Jahr 2008!!! In gewisser Weise wundert es mich, dass sich nie jemand darüber beschwert.

Die mit Abstand am häufigsten nachgefragte Funktion, die ich nie implementiert habe, waren Kategorien. Sie steht irgendwie hier drin. Ich habe vergessen, warum ich sie nie ausgeliefert habe. Ich weiß nicht mehr, welche letzten Dinge noch erledigt werden mussten, aber vielleicht wäre das ein guter Anfang Was muss man angehen? Es gibt auch Produzenten und Ursprünge, die nie ganz abgeschlossen wurden.

Ich habe auch eine ganze Reihe anderer Repos und kleiner Experimente, die ich im Laufe der Jahre gemacht habe. Ich war immer fasziniert von der Idee der Bestandshöhenvorhersage. Irgendwo gibt es ein in Go geschriebenes Tool zur Datensatz-Dump-Analyse, mit dem man die CSV-Dumps für einen bestimmten Produktbestand analysieren kann über einen bestimmten Zeitraum hinweg. Ich würde das Zeug auch gerne veröffentlichen, wenn Interesse besteht.

In Bearbeitung (in Arbeit)

Ich belasse es vorerst hier und warte auf eine Antwort von Ihnen. Ich würde diese Wissensbasis gerne auf jede Art und Weise erweitern, die die Leute sehen möchten (Screencasts, Interviews, Inline-Dokumentation usw.). Ich möchte auch, dass Sie dasselbe tun. Wenn Sie sich nicht sicher sind, fragen Sie. ❤️