lcbo api

Bonjour , bienvenue à l' API LCBO ?

Si vous vous demandez « qu'est-ce qu'une API LCBO ? », laissez-moi vous expliquer. En Ontario, au Canada, toutes les ventes de boissons alcoolisées passent par une société gouvernementale appelée la Régie des alcools de l'Ontario (LCBO), qui gère la vente au détail et la distribution de boissons alcoolisées dans toute la province. La LCBO possède de nombreux magasins de détail et un site Web qui héberge un catalogue de chaque produit, magasin et même des niveaux de stock. Ils publient un catalogue saisonnier avec des recettes, des éditoriaux et d'autres contenus appelés Food & Drink. Ils génèrent également des milliards de dollars de revenus chaque année pour notre système de santé public. C'est une situation fascinante quand on y pense, d'autres endroits ont des systèmes similaires mais, à ma connaissance, aucun n'a l'ampleur et la profondeur de la LCBO. Alors, maintenant tu sais ce que c'est, plutôt cool hein ?

Cela pourrait vous intéresser même si vous ne vivez pas en Ontario, au Canada, si :

• Vous souhaitez accéder à de nombreuses données pour apprendre ou tester
• Vous êtes curieux de savoir comment fonctionnent certains types de robots d'exploration Web
• Vous êtes curieux de savoir à quoi pourrait ressembler une application Rails de production s'étalant sur 10 ans de développement.

Un avis important ?

Tout au long de ce projet, j'ai eu beaucoup de mal à accepter l'idée d'accepter un soutien financier. D’un côté, l’API de la LCBO en avait besoin, de l’autre, j’étais fatigué des complications que cela entraînerait. Eh bien, j’ai maintenant LA solution PARFAITE à ce problème !

Je suis actuellement sous traitement pour un cancer du sang, en particulier un lymphome diffus à grandes cellules B. Je vais bientôt écrire davantage à ce sujet ailleurs, mais au cours de l'année écoulée, des gens de partout m'ont soutenu de toutes les manières possibles, et cela m'a changé. Je veux que nous fassions quelque chose de grand pour montrer que nous nous en soucions aussi !

Si vous avez déjà voulu soutenir ce projet dans le passé, faites un don à Hamilton Health Sciences au nom de LCBO API, ils me sauvent la vie.

Faites un don à Hamilton Health Sciences

Je suis en traitement au Juravinski Cancer Center, mais en réalité, vous pouvez choisir n'importe quelle option ou laisser celle par défaut. Peu importe que le montant soit petit ou grand, ils m'en informeront lorsque vous ferez un don. Je vais dresser une liste pour suivre le total, voyons combien nous pouvons récolter !

Enfin, j'aimerais faire une mention spéciale à mon lieu de travail, Crowdmark. Ils ont été incroyablement gentils et compréhensifs pendant tout cela, et je n’aurais littéralement pas pu faire cela sans eux. Nous travaillons sans relâche pour faire progresser le statu quo en matière d’évaluation dans l’enseignement supérieur. Si vous vous souciez de l'éducation et de l'apprentissage, je vous invite à nous consulter.

Arrière-plan

À l'automne 2008, j'étais un nouveau développeur Web avec quelques années d'expérience à mon actif. J'avais soif de défi et de reconnaissance. Les applications devenaient une chose à l’époque et je voulais vraiment en créer une. J'ai décidé que je voulais en créer une qui m'obligerait d'abord à créer cette API. Je n'ai jamais créé cette application ?

Soyez gentil

Si vous examinez cette base de code assez longtemps, vous risquez de trouver des moments de frustration, des impasses, des confusions déroutantes, etc. J'espère vraiment que vous ne vous concentrez pas sur cela ou sur toute négativité que vous pourriez trouver. Je ne suis plus cette personne, et je ne veux pas non plus que tu sois cette personne. Je suis un livre ouvert là-dessus ! Ouvrez un ticket et posez-moi une question, je serai aussi honnête et respectueux que possible, je vous demande seulement de faire de même.

Licence

Je publie ce projet sous GNU GPLv3, je pense que c'est l'option la plus juste et la plus responsable pour un projet comme celui-ci. Si vous ressentez le contraire, ouvrez un problème et nous pourrons en discuter ouvertement. Je vous demande seulement, respectueusement, de ne pas réutiliser l'image de marque et le design. Je suis d'accord avec la réutilisation de la documentation, mais le style, l'identité et l'image de marque doivent être modifiés si vous souhaitez déployer votre propre version cloisonnée de cette application.

Faites de grands rêves !

Et si, au lieu d’une application monolithique essayant de tout faire dans un seul style, en un seul endroit, nous voyions plus grand ? Et si le robot d'exploration était à nouveau un projet distinct, responsable de la collecte et de la normalisation des données, d'autres pourraient créer des nœuds API sur les plates-formes de leur choix, ces nœuds s'enregistreraient auprès du fournisseur de données et recevraient des données mises à jour dès qu'elles seraient mises à disposition et fourniraient ces données à utilisateurs de tous types.

Au lieu que des dizaines de serveurs API similaires tentent de faire la même chose, en luttant pour les ressources de LCBO.com, nous pourrions concentrer nos efforts sur la création de valeur sur ces données au lieu de nous battre pour en devenir propriétaires. Nous pourrions impliquer d'autres disciplines pour générer une nouvelle valeur au-delà de l'évidence, impliquer les communautés de la bière artisanale et du vin, bâtir sur cela, faire en sorte que le tout dépasse le seul cadre de l'Ontario.

Je ne sais pas dans quelle mesure une telle chose serait réalisable, mais je sais que si d'autres sont intéressés, j'adorerais avoir ces discussions.

En outre, nous devrions peut-être envisager de facturer aux utilisateurs professionnels des frais raisonnables pour accéder aux nœuds API, cet argent pourrait être utilisé pour financer les coûts d'hébergement afin de maintenir les choses durables, il pourrait également être utilisé pour financer des programmes de soutien pour les personnes qui ne peuvent pas boire, ou qui ne veulent pas boire, ou qui veulent boire moins, pour redonner à nos communautés et réellement faire une différence.

Mais j'ai besoin que d'autres m'aident à partager le fardeau du maintien et de la gestion de tout cela, ma santé et mon bonheur et ceux de ma famille sont la priorité n°1, suivis de ma carrière, puis de mes amis et de ma communauté. Ce projet ne peut plus être mon passe-temps n°1, il n'est pas durable pour moi et ce n'est pas sain pour moi. Mais si ce message vous inspire, n'hésitez pas à me contacter, idéalement ouvertement, mais en privé au début, ça va aussi.

J'espère que cela vous excite !

Je n'ai pas pu m'en empêcher, j'ai écrit davantage sur mes idées à ce sujet : doc/lcboapi-proposed.md

Commencer

Maintenant que cela est réglé, nous pouvons commencer à comprendre pour qui j'ai vraiment fait cela, et ce qui m'a enthousiasmé et inspiré pour le faire en premier lieu : l'opportunité d'apprendre et de grandir et d'aider les autres à faire de même. Pour ceux d’entre vous qui sont curieux, voyons où cela nous mène ?

Vous exécutez l'application Rails ?

Vous pouvez probablement exécuter l'application directement sur votre environnement hôte, cela ne nécessite rien de trop sophistiqué en ce qui concerne les dépendances du système. Je développe sur du matériel Apple, si vous le faites aussi, vous réussirez peut-être à utiliser Postgres.app et Homebrew pour installer Redis. Sinon, vous pouvez utiliser Docker.

Si vous avez de l'expérience avec une autre plate-forme, veuillez créer un PR ou un problème et nous pourrons travailler à l'ajout de votre plate-forme au README.

De plus, si ce qui suit ici n'a aucun sens pour vous, ouvrez un problème, peut-être pourrions-nous faire un screencast pour démontrer le processus, ou peut-être que quelqu'un qui est bon dans ce domaine s'en chargerait ?

Ce que je décris ci-dessous n'est qu'une façon de configurer un environnement de développement pour exécuter l'API LCBO sur votre ordinateur. Si d'autres ont des améliorations (il y a de la place pour beaucoup, un script de point d'entrée pour amorcer la base de données de développement par exemple) ou même des approches différentes, comme utiliser Vagrant + VirtualBox, ouvrir un ticket ou un PR, je suis heureux de les ajouter.

Si vous voulez aider, je veux vous permettre.

Premiers pas

Configuration de config/secrets.yml et .env

Tout d'abord, vous devrez configurer une configuration qui n'est pas fournie dans le référentiel public. La raison pour laquelle cela est fait est de protéger les données privées telles que les clés API et les jetons secrets, mais aussi parce que certains développeurs peuvent préférer des paramètres légèrement différents pour leurs préférences personnelles, etc.

Vous devrez créer quelques fichiers, config/secrets.yml et .env . Il existe des versions de modèles dans le dépôt sous config/secrets.yml.example et .env.example , vous pouvez copier ces fichiers pour commencer :

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

Si vous souhaitez simplement démarrer l'application et y accéder localement, vous devriez être prêt à partir à ce stade. Si vous souhaitez pouvoir utiliser le robot d'exploration et lui permettre d'enregistrer un instantané enregistré sur Amazon S3, vous devrez ajouter vos informations d'identification AWS et votre compartiment à config/secrets.yml .

Le reste des paramètres n'a vraiment d'importance que dans un environnement de production, n'est pas vraiment utilisé ou n'a d'importance que si vous n'aimez pas la préférence par défaut. Comme toujours, si vous avez besoin de précisions, ouvrez et publiez et je serai heureux de vous aider.

Faire fonctionner l'application pour la première fois

Tout d’abord, vous devrez installer le client Docker pour votre système, vous pouvez le découvrir ici. Une fois que vous avez installé Docker, vous pouvez commencer :

Ensuite, vous devrez construire les conteneurs :

 docker-compose build

Lorsque cela est fait, vous pouvez démarrer le tout en émettant :

 docker-compose up

À ce stade, vous n'avez aucune donnée dans la base de données, donc si vous chargez l'application http://localhost:3000, cela ne fera pas grand-chose, elle sert des données après tout, et il n'y a aucune donnée dedans. Alors faisons quelque chose à ce sujet.

Allez-y et fermez les conteneurs :

 Ctrl-C

Cela signifie, appuyez simultanément sur les touches Control + C

Vous pouvez télécharger une archive du dernier vidage de la base de données de production à partir de mon compte personnel Amazon S3 ici. Veuillez noter qu'il existe des tables sensibles (emails, utilisateurs, clés) et que les données ont été exclues de ce fichier.

Téléchargez et extrayez l'archive dans le répertoire tmp de ce projet :

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

Le fichier fait environ 300 Mo, le téléchargement peut donc prendre un certain temps en fonction de votre vitesse de connexion (cela se produit sur la ligne qui commence par curl ).

Une fois que vous avez téléchargé et extrait le fichier de base de données, vous pouvez charger les données dans la base de données :

 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'

La première ligne, se terminant par rake db:create créera les schémas de base de données dans Postgres pour le développement et les tests, la deuxième ligne chargera le dump de la base de données dans la base de données de développement. La barre de progression indique la quantité de données qui a été transmise à la base de données. Une fois celle-ci terminée, les index seront créés. Cela peut prendre un certain temps en fonction de votre machine, cela représente une bonne quantité de données. Ensuite, vous pouvez relancer l'application :

 docker-compose up

Vous pouvez également supprimer en toute sécurité l'archive et le fichier SQL extrait de votre répertoire tmp à ce stade.

Si vous trouvez que taper docker-compose encore et encore est fastidieux, examinez les alias du shell

Vous pouvez ajouter une ligne d'alias à votre profil shell comme alias dc=docker-compose , puis vous pouvez simplement taper dc au lieu d'avoir à taper docker-compose à chaque fois. ✅

Pensez à d’autres alias que vous pourriez créer pour améliorer encore davantage cela ?

Maintenant, accédez à http://localhost:3000/products/438457

Boom. L'API LCBO est en cours d'exécution sur votre ordinateur ! ? ? ?

Exécuter l'application à partir de maintenant

Lorsque vous avez fini de travailler sur l'application, exécutez simplement Ctrl+C pour tout arrêter. La prochaine fois que vous voudrez y travailler à nouveau, exécutez docker-compose up et vous êtes prêt à partir !

Reconstruction (installation groupée)

Si vous ajoutez une nouvelle gemme au Gemfile , vous devrez réinstaller les packages et mettre à jour les dépendances. Docker est assez doué pour cela, il peut savoir quand Gemfile change et il sait reconstruire le conteneur app pour vous.

Ouvrir une console Rails

Pour lancer une console Rails et inspecter les objets à l'intérieur de l'application :

 docker-compose exec app rails c

Une fois que cela est exécuté, vous pouvez faire des choses comme :

Récupérez le premier produit de la base de données :

 Product.first

Trouvez le magasin LCBO n° 25 (mon magasin local) :

 Store.find(25)

Si vous modifiez le code dans l'application, vous devrez émettre le reload! commande dans la console pour actualiser les modifications.

Exécution de tests

Dans le dossier spec , vous trouverez la suite de tests pour l’API LCBO. Ce n'est malheureusement pas exhaustif, mais ce n'est pas trop mal non plus. J'ai eu du mal tout au long de ma carrière à maintenir des suites de tests dont je suis satisfait. Nous devrions améliorer ces tests !

Pour exécuter la suite de tests :

 docker-compose exec app rspec

Vous verrez un tas de points verts . , chacun d'entre eux représente un cas de test réussi. C'est bien. Si une panne survient, vous verrez un F rouge, c'est mauvais... JE PLAQUE ! En fait, c'est bon ! Les tests vous donnent le pouvoir de modifier des éléments dans une base de code existante et de voir si vous provoquez des régressions dans les fonctionnalités existantes. Bien sûr, rien n’est parfait, mais je peux vous le dire sans aucun doute, par expérience, que les tests sont bons.

À mesure que les applications deviennent de plus en plus grandes et de plus en plus complexes, le fait de ne pas avoir de tests devient un véritable cauchemar, ce qui rend la modification de votre application et l'ajout de fonctionnalités extrêmement fragiles. Des choses comme l'utilisation de langages avec des systèmes de types et d'autres paramètres de programmation différents peuvent également grandement aider, mais je suis d'avis qu'il n'y a vraiment pas de remplacement pour au moins une solide suite de tests d'acceptation.

Chenille

C’est la partie de l’API de la LCBO qui rend tout cela possible. Les robots d'exploration de sites Web complexes sont difficiles à créer et à maintenir. La première version de l'API LCBO comportait une suite de tests complète pour le robot d'exploration. Lorsque tout a changé il y a de nombreuses années, j'ai abandonné cette base de code et j'ai simplement créé quelque chose aussi vite que possible dans celle-ci.

La logique du robot d'exploration se trouve dans lib/crawler.rb , à partir de là, vous verrez toutes les différentes tâches qui se succèdent pour englober une analyse complète des sites Web de la LCBO.

La logique de l'analyseur se trouve dans lib/lcbo.rb et dans tous les différents fichiers de lib/lcbo/* , cela inclut toutes les différentes requêtes qui doivent se produire, et le code chargé de transformer les données de ces requêtes en données structurées. cela peut finalement aller dans la base de données.

Ramper poliment

J'ai conçu le robot pour effectuer des requêtes en série, c'est une très bonne approche à adopter lorsque vous explorez un site Web. C'est simple, c'est toujours le meilleur itinéraire à emprunter si vous le pouvez, et c'est poli. Nous pourrions lancer n tâches AWS Lambda et explorer chaque page de LCBO.com en quelques secondes, mais ce serait impoli, et nous ferions probablement un DDoS sur leur site Web momentanément, ce qui n'est pas bon.

Application Gestionnaire ( /manager )

Cela englobe une application Ember, lorsque vous vous inscrivez à l'API LCBO et générez des clés API, c'est avec cela que vous interagissez. C'est assez obsolète, je n'ai pas essayé de le construire. J'utilise Ember depuis le premier jour, donc si vous avez des questions à ce sujet, posez des questions. En fait, j'aimerais beaucoup discuter de cette partie de l'API de la LCBO et travailler avec vous tous pour l'améliorer.

Site statique ( /static )

Celui-ci contient un site Middleman, lorsque vous visitez lcboapi.com, c'est ce que vous regardez. Il contient également une très petite application React (également obsolète) qui est le truc "Essayez-le" à droite de la page d'accueil. Il possède son propre Gemfile et son script de construction static/generate , lorsqu'il est exécuté, il construit le site et synchronise les modifications dans le dossier public . Dans les applications Rails, le dossier public est servi comme contenu statique.

Impasses

Il y a BEAUCOUP d'impasses dans cette base de code, des branches qui ont parcouru 40 à 60 à 80 % du chemin vers une fonctionnalité puis qui ont stagné, des expériences, etc. Comme toujours, si vous trouvez quelque chose qui vous plaît ? déposez simplement un problème et je vous répondrai dès que possible.

Ce serait également cool si nous pouvions résoudre certaines des impasses ici, je serais très intéressé par l'ajout enfin de JSON:API et GraphQL. La conception actuelle de la réponse API date de 2008 !!! D'une certaine manière, je suis un peu surpris que personne ne s'en plaigne jamais.

La fonctionnalité n°1, de loin la plus demandée, que je n'ai jamais implémentée était les catégories, elle est en quelque sorte ici, j'ai oublié pourquoi je ne l'ai jamais expédiée, je ne me souviens pas des éléments finaux qui devaient se mettre en place, mais ce serait peut-être une bonne première. chose à aborder ? Il y a aussi Producers et Origins qui n’ont jamais vraiment été terminés.

J'ai aussi tout un tas d'autres dépôts et petites expériences que j'ai faites au fil des ans, j'ai toujours été fasciné par l'idée de prédiction du niveau de stock, quelque part il y a un outil d'analyse de dump d'ensemble de données écrit en Go pour analyser les dumps CSV pour un inventaire de produits particulier. sur un certain temps. Je serais heureux de publier ce genre de choses aussi s'il y a de l'intérêt.

En cours (Travaux en cours)

Je vais le laisser ici pour le moment et j'attendrai votre réponse. J'aimerais continuer à enrichir cette base de connaissances de la manière que les gens souhaitent voir (screencasts, interviews, documentation en ligne, etc.). Je veux également que vous fassiez de même, si vous n'êtes pas sûr, demandez. ❤️