lcbo api
1.0.0
Olá, bem-vindo à API LCBO?
Se você está se perguntando "o que é uma API LCBO?", deixe-me explicar. Em Ontário, Canadá, todas as vendas de bebidas alcoólicas passam por uma empresa estatal chamada Liquor Control Board of Ontario (LCBO), que lida com o varejo e a distribuição de bebidas alcoólicas em toda a província. A LCBO possui inúmeras lojas de varejo e um site que hospeda um catálogo de todos os produtos, lojas e até mesmo níveis de estoque. Eles publicam um catálogo sazonal com receitas, editoriais e outros conteúdos chamado Food & Drink. Eles também contribuem anualmente com bilhões de dólares em receitas para o nosso sistema público de saúde. É uma situação fascinante quando você pensa sobre isso, outros lugares têm sistemas semelhantes, mas que eu saiba, nenhum tem a amplitude e profundidade da LCBO. Então, agora você já sabe o que é, muito legal, né?
Isso pode ser interessante para você, mesmo que você não more em Ontário, Canadá, se:
Ao longo de todo este projeto, lutei enormemente com a ideia de aceitar apoio financeiro. Por um lado a API LCBO precisava disso, por outro eu estava cansado das complicações que isso causaria. Bem, agora tenho A solução PERFEITA para este problema!
Estou em tratamento para câncer no sangue agora, especificamente linfoma difuso de grandes células B. Em breve escreverei mais sobre isso em outro lugar, mas durante o ano passado pessoas de todos os lugares me apoiaram de todas as maneiras que puderam, e isso me mudou. Quero que façamos algo grande para mostrar que também nos importamos!
Se você já quis apoiar este projeto no passado, por favor, faça uma doação para Hamilton Health Sciences em nome da API LCBO, eles estão salvando minha vida.
Doe para Hamilton Health Sciences
Estou em tratamento no Juravinski Cancer Center, mas realmente você pode escolher qualquer opção ou deixar a padrão. Não importa se o valor é pequeno ou grande, eles vão me avisar quando você doar. Vou tabular uma lista para acompanhar o total, vamos ver quanto conseguimos arrecadar!
Finalmente, gostaria de fazer uma menção especial ao meu local de trabalho, Crowdmark. Eles foram incrivelmente gentis e compreensivos durante tudo isso, e eu literalmente não teria sido capaz de fazer isso sem eles. Estamos a trabalhar incansavelmente para fazer avançar o status quo da avaliação no ensino superior. Se você se preocupa com educação e aprendizagem, recomendo que nos consulte.
No outono de 2008, eu era um desenvolvedor web recém-formado, com alguns anos de experiência. Eu estava faminto por um desafio e por algum reconhecimento. Os aplicativos estavam se tornando uma coisa na época e eu queria muito criar um. Decidi que queria construir um que exigisse primeiro construir esta API. Eu nunca construí esse aplicativo?
Se você examinar essa base de código por tempo suficiente, provavelmente encontrará momentos de frustração, becos sem saída, confusão, etc. Eu realmente espero que você não se concentre nisso ou em qualquer negatividade que possa encontrar. Não sou mais essa pessoa e também não quero que você seja essa pessoa. Eu sou um livro aberto sobre isso! Abra um problema e me faça uma pergunta, serei o mais honesto e respeitoso possível, só peço que você faça o mesmo.
Estou lançando este projeto sob GNU GPLv3, acho que esta é a opção mais justa e responsável para um projeto como este. Se você pensa diferente, abra um problema e poderemos discutir abertamente sobre isso. Peço apenas, respeitosamente, que não reutilizem a marca e o design. Concordo com a reutilização da documentação, mas o estilo, a identidade e a marca devem ser alterados se você quiser implantar sua própria versão isolada deste aplicativo.
E se em vez de um aplicativo monolítico tentar fazer tudo em um estilo, em um só lugar, pensássemos maior? E se o rastreador fosse um projeto separado novamente, responsável por coletar e normalizar dados, outros pudessem construir nós de API em quaisquer plataformas que desejassem, esses nós se registrariam no provedor de dados e receberiam dados atualizados à medida que fossem disponibilizados e forneceriam esses dados para usuários de todos os tipos diferentes.
Em vez de dezenas de servidores API semelhantes tentando fazer a mesma coisa, lutando pelos recursos do LCBO.com, poderíamos concentrar nossos esforços na construção de valor nesses dados, em vez de lutar pela propriedade sobre eles. Poderíamos envolver outras disciplinas para gerar um novo valor além do óbvio, envolver as comunidades de cerveja artesanal e vinho, desenvolver isso, torná-lo maior do que apenas Ontário.
Não sei até que ponto algo assim seria viável, mas sei que se outras pessoas estiverem interessadas, adoraria ter essas discussões.
Além disso, talvez devêssemos considerar cobrar dos usuários corporativos uma taxa razoável para acessar os nós da API, esse dinheiro poderia ser usado para financiar os custos de hospedagem para manter as coisas sustentáveis, também poderia ser usado para financiar programas de apoio para pessoas que não podem beber, ou que não querem beber, ou que querem beber menos, para retribuir às nossas comunidades e realmente fazer a diferença.
Mas preciso que outros ajudem a partilhar o fardo de manter e gerir tudo isto, a saúde e a felicidade minha e da minha família são a prioridade número 1, seguida pela minha carreira, e depois pelos meus amigos e comunidade. Este projeto não pode mais ser minha pia número 1, não é sustentável para mim e não é saudável para mim. Mas se você se sentir inspirado por esta mensagem, por favor, entre em contato comigo, de preferência abertamente, mas em particular no início também está tudo bem.
Espero que isso te excite!
Não pude evitar, escrevi mais sobre minhas ideias sobre isso: doc/lcboapi-proposed.md
Agora, com isso resolvido, podemos começar a descobrir por quem eu realmente fiz isso e o que me deixou animado e inspirado para fazer isso em primeiro lugar: a oportunidade de aprender e crescer e de ajudar outros a fazer o mesmo. Para vocês que estão curiosos, vamos ver aonde isso vai dar?
Provavelmente, você pode executar o aplicativo diretamente em seu ambiente host, pois não requer nada muito sofisticado no que diz respeito às dependências do sistema. Eu desenvolvo em hardware Apple, se você também fizer isso, poderá ter sucesso usando Postgres.app e Homebrew para instalar o Redis. Caso contrário, você pode usar o Docker.
Se você tem experiência com outra plataforma, faça um PR ou um problema e poderemos trabalhar para adicionar sua plataforma ao README.
Além disso, se o que segue aqui não faz sentido para você, abra uma issue, talvez pudéssemos fazer um screencast para demonstrar o processo, ou talvez alguém aí que seja bom nisso faria isso?
O que descrevo abaixo é apenas uma maneira de configurar um ambiente de desenvolvimento para executar a API LCBO em seu computador. Se outros tiverem melhorias (há espaço para muitos, um script de ponto de entrada para inicializar o banco de dados de desenvolvimento, por exemplo) ou até mesmo abordagens diferentes, como usar Vagrant + VirtualBox, abrir um problema ou um PR, ficarei feliz em adicioná-los.
Se você quiser ajudar, quero capacitá-lo.
config/secrets.yml e .envPrimeiro, você precisará definir algumas configurações que não são fornecidas no repositório público. A razão pela qual isso é feito é para proteger dados privados, como chaves de API e tokens secretos, mas também porque alguns desenvolvedores podem preferir configurações ligeiramente diferentes para suas preferências pessoais e coisas assim.
Existem alguns arquivos que você precisará criar, config/secrets.yml e .env . Existem versões de modelo no repositório em config/secrets.yml.example e .env.example , você pode copiar esses arquivos para começar:
cp config/secrets.yml.example config/secrets.yml
cp .env.example .env
Se você deseja apenas inicializar o aplicativo e acessá-lo localmente, você deve estar pronto para prosseguir neste momento. Se quiser usar o rastreador e fazer com que ele salve um snapshot salvo no Amazon S3, você precisará adicionar suas credenciais e bucket da AWS a config/secrets.yml .
O restante das configurações realmente importa apenas em um ambiente de produção, não é realmente usado ou só importa se você não gostar da preferência padrão. Como sempre, se precisar de esclarecimentos, abra e emita e ficarei feliz em ajudar.
Primeiro, você precisará instalar o cliente Docker para o seu sistema, você pode descobrir mais sobre isso aqui. Depois de instalar o Docker, você pode começar:
Em seguida, você precisará construir os contêineres:
docker-compose build
Quando isso for feito, você pode inicializar tudo emitindo:
docker-compose up
Neste ponto, você não tem nenhum dado no banco de dados, então se você carregar o aplicativo, http://localhost:3000, ele não fará muito, afinal, ele fornece dados e não há dados nele. Então vamos fazer algo sobre isso.
Vá em frente e desligue os contêineres:
Ctrl-C
Isso significa que pressione as teclas Control + C simultaneamente.
Você pode baixar um arquivo do despejo de banco de dados de produção mais recente da minha conta pessoal do Amazon S3 aqui. Observe que existem tabelas confidenciais (e-mails, usuários, chaves) e que os dados foram excluídos deste arquivo.
Baixe e extraia o arquivo no diretório tmp deste projeto:
cd tmp
curl -O https://heycarsten.s3.amazonaws.com/lcboapi-2019-01-21.tgz
tar xzf lcboapi-2019-01-21.tgz
cd ..
O arquivo tem cerca de 300 MiB, então pode demorar um pouco para fazer o download dependendo da velocidade da sua conexão (isso acontece na linha que começa com curl ).
Depois de baixar e extrair o arquivo do banco de dados, você poderá carregar os dados no banco de dados:
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'
A primeira linha, terminando em rake db:create , criará os esquemas de banco de dados no Postgres para desenvolvimento e teste, a segunda linha carregará o dump do banco de dados no banco de dados de desenvolvimento. A barra de progresso indica quanto dos dados foram canalizados para o banco de dados, uma vez concluído, os índices serão construídos. Isso pode levar algum tempo dependendo da sua máquina, é uma quantidade razoável de dados. Então você pode iniciar o aplicativo novamente:
docker-compose up
Você também pode excluir com segurança o arquivo morto e o arquivo SQL extraído de seu diretório tmp neste momento.
Se você acha que digitar
docker-composeé tedioso repetidamente, procure nos aliases do shellVocê pode adicionar uma linha de alias ao seu perfil de shell como
alias dc=docker-composee então você pode simplesmente digitardcem vez de digitardocker-composetodas as vezes. ✅Pense em outros aliases que você poderia criar para melhorar ainda mais?
Agora, navegue para http://localhost:3000/products/438457
Bum. Você tem a API LCBO rodando no seu computador! ? ? ?
Quando terminar de trabalhar no aplicativo, basta emitir Ctrl+C para desligar tudo. Na próxima vez que você quiser trabalhar nisso novamente, execute docker-compose up e pronto!
Se você adicionar uma nova gem ao Gemfile , precisará reinstalar os pacotes e atualizar as dependências. O Docker é muito bom nisso, ele pode dizer quando Gemfile muda e sabe como reconstruir o contêiner app para você.
Para iniciar um console Rails e inspecionar objetos dentro da aplicação:
docker-compose exec app rails c
Quando estiver em execução, você pode fazer coisas como:
Busque o primeiro produto no banco de dados:
Product.first
Encontre a loja de varejo nº 25 da LCBO (minha loja local):
Store.find(25)
Se você alterar o código no aplicativo, será necessário emitir a reload! comando no console para atualizar as alterações.
Dentro da pasta spec , você encontrará o conjunto de testes da API LCBO. Lamentavelmente, não é abrangente, mas também não é tão ruim. Lutei durante toda a minha carreira para manter conjuntos de testes com os quais estou satisfeito. Deveríamos melhorar esses testes!
Para executar o conjunto de testes:
docker-compose exec app rspec
Você verá um monte de pontos verdes . , cada um deles representa um caso de teste aprovado. Isso é bom. Se ocorrer uma falha, você verá um F vermelho, isso é ruim... SÓ BRINCADEIRA! Na verdade é bom! Os testes dão a você o poder de mudar coisas em uma base de código existente e ver se você causa alguma regressão à funcionalidade existente. Claro que nada é perfeito, mas posso afirmar sem dúvida que, por experiência própria, os testes são bons.
À medida que os aplicativos ficam cada vez maiores e mais complexos, não ter testes se torna um pesadelo literal, tornando a alteração do seu aplicativo e a adição de recursos um processo extremamente frágil. Coisas como usar linguagens com sistemas de tipos e outros paradigmas de programação diferentes também podem ajudar muito nisso, mas sou da opinião de que realmente não há substituto para pelo menos um conjunto sólido de testes de aceitação.
Esta é a parte da API LCBO que torna tudo possível. Os rastreadores de sites complicados são difíceis de construir e manter. A primeira versão da API LCBO tinha um conjunto de testes completo para o crawler, quando tudo mudou há muitos anos, desisti daquela base de código e apenas construí algo o mais rápido que pude nesta.
A lógica do rastreador está localizada em lib/crawler.rb , a partir daí você verá todas as diversas tarefas que acontecem em sucessão para abranger um rastreamento completo dos sites LCBO.
A lógica do analisador está localizada em lib/lcbo.rb e em todos os vários arquivos dentro de lib/lcbo/* , isso inclui todas as diversas solicitações que precisam acontecer e o código responsável por transformar os dados dessas solicitações em dados estruturados que pode finalmente ir para o banco de dados.
Eu projetei o rastreador para realizar solicitações em série. Essa é uma abordagem muito boa quando você está rastreando um site. É simples para quem é sempre o melhor caminho a seguir, se possível, e é educado. Poderíamos disparar trabalhos do AWS Lambda e rastrear todas as páginas do LCBO.com em alguns segundos, mas isso seria rude e provavelmente faríamos um DDoS em seu site momentaneamente, o que não é bom.
/manager )Isso abrange um aplicativo Ember, quando você se inscreve na API LCBO e gera chaves de API, é com isso que você está interagindo. Está bastante desatualizado, não tentei construí-lo. Tenho usado o Ember desde o dia zero, então se você tiver alguma dúvida sobre isso, faça perguntas. Na verdade, eu adoraria discutir esta parte da API LCBO e trabalhar com todos vocês para melhorá-la.
/static ) Este contém um site intermediário, quando você visita lcboapi.com é isso que você está vendo. Ele também contém um aplicativo React muito pequeno (também desatualizado), que é o item "Experimente" à direita da página inicial. Ele possui seu próprio Gemfile e script de construção static/generate , quando executado, ele cria o site e sincroniza as alterações na pasta public . Em aplicativos Rails, a pasta public é servida como conteúdo estático.
Existem MUITOS becos sem saída nesta base de código, ramificações que percorreram 40-60-80% do caminho para um recurso e depois estagnaram, experimentos, etc. basta registrar um problema e responderei assim que puder.
Também seria legal se pudéssemos resolver alguns dos becos sem saída aqui, eu estaria muito interessado em finalmente adicionar JSON:API e GraphQL. O design de resposta da API atual é de 2008!!! De certa forma, estou um pouco surpreso que ninguém reclame disso.
O recurso mais solicitado, de longe, que nunca implementei foram as categorias, está meio aqui, esqueci por que nunca o enviei, não me lembro quais coisas finais tiveram que se encaixar, mas talvez fosse um bom primeiro coisa para resolver? Há também Produtores e Origens que nunca foram totalmente concluídos.
Eu também tenho um monte de outros repositórios e pequenos experimentos que fiz ao longo dos anos, sempre fui fascinado pela ideia de previsão do nível de estoque, em algum lugar há uma ferramenta de análise de despejo de conjunto de dados escrita em Go para analisar os despejos CSV para um inventário de produto específico ao longo de um conjunto de tempo. Eu ficaria feliz em lançar esse material também se houver interesse.
Vou deixar isso aqui por enquanto e vou esperar uma resposta sua. Eu adoraria continuar acrescentando a esta base de conhecimento da maneira que as pessoas quiserem ver (screencasts, entrevistas, documentação in-line, etc.). Também quero que você faça o mesmo, se não tiver certeza, pergunte. ❤️
