Code Monkey home page Code Monkey logo

brasilapi's Introduction

Vamos transformar o Brasil em uma API?

Powered by Vercel

Quality Gate Status Code Smells Maintainability Rating Security Rating Vulnerabilities

Motivo

Acesso programático de informações é algo fundamental na comunicação entre sistemas, mas, para nossa surpresa, uma informação tão útil e pública quanto um CEP não consegue ser acessada diretamente por um navegador por conta da API dos Correios não possuir CORS habilitado.

Dado a isso, este projeto experimental tem como objetivo centralizar e disponibilizar endpoints modernos com baixíssima latência utilizando tecnologias como Vercel Smart CDN responsável por fazer o cache das informações em atualmente 23 regiões distribuídas ao longo do mundo (incluindo Brasil). Então não importa o quão devagar for a fonte dos dados, nós queremos disponibilizá-la da forma mais rápida e moderna possível.

Documentação

Caso deseje saber mais sobre os detalhes das integrações consulte nossa documentação OpenAPI.

Como contribuir

Através do Next.js, um framework utilizado por empresas como Marvel, Twitch, Nike, Hulu, TypeForm, Nubank, Ferrari, TikTok, Square Enix, entre outras, estamos construindo a página de apresentação do projeto e, por ser um framework híbrido, ele possibilita a construção e deploy de APIs com o mínimo de configuração possível em uma infraestrutura autoescalável da Vercel, a mesma que conta com recursos sensacionais como a Vercel Smart CDN.

Caso você esteja lendo esta versão de README, você está pegando o projeto num estágio extremamente inicial, porém empolgante, pois há várias coisas a serem definidas. Então caso queira contribuir, utilize as issues para entender quais pontos ainda não foram resolvidos, conversar conosco e contribuir tanto com idéias técnicas, quanto de quais APIs podem ser criadas.

Veja mais detalhes sobre Como contribuir no arquivo CONTRIBUTING.md

Termos de Uso

O BrasilAPI é uma iniciativa feita de brasileiros para brasileiros, por favor, não abuse deste serviço. Estamos em beta e ainda elaborando os Termos de Uso, mas por enquanto por favor não utilize formas automatizadas para fazer "crawling" dos dados da API. Um exemplo prático disso foi quando um dos maiores provedores de telefonia do Brasil estava validando novamente todos os CEPs (de 00000000 até 99999999) e ultrapassando em cinco vezes o limite atual da nossa conta no servidor. O volume de consultas deve ter a natureza de uma pessoa real requisitando um determinado dado. Para consultas com um alto volume automatizado forneceremos posteriormente alguma solução, como, por exemplo, permitir o download de toda a base de CEPs em uma única requisição.

Pessoas que já contribuíram

📦 Bibliotecas da comunidade

Abaixo segue uma lista de integrações com a BrasilApi fornecidas pela comunidade (muito obrigado a eles!):

Go

JS

Flutter

.Net

PHP

Python

Ruby

Rust

Java

Delphi

V

Autores


@filipedeschamps

@lucianopf

brasilapi's People

Contributors

alessandrojean avatar allangrds avatar caiocesarp avatar carlosziegler avatar cuducos avatar danielramosbh74 avatar dependabot[bot] avatar enzoferraribf avatar filipedeschamps avatar guilhermeasn avatar jvolima avatar kaiquefeng avatar lorhansohaky avatar lucianopf avatar marcosgarcez avatar marlonhenq avatar matheusvellone avatar met4tron avatar murilohns avatar paulo-santana avatar paulogdm avatar pedrosancao avatar raphaeloliveiramoura avatar rbressans avatar rodriandreotti avatar samycici avatar skaylan avatar weslleynasrocha avatar willianagostini avatar yardz avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

brasilapi's Issues

Dados do INMET e do CPTEC

Algumas instituições governamentais, como a Defesa Civil, necessitam utilizar em sua operação diaria dados do INMET e do CPTEC, seria um puta avanço ter isso tudo em uma API. Em um sistema que desenvolvi, precisei fazer uma gambiarra usando CURL para pegar capturar esses dados e conseguir trabalhar com eles.

Cache dos dados

Indicado pelo @lucianopf parece ser uma delicinha implementar o cache control pela Smart CDN deles: https://zeit.co/docs/v2/serverless-functions/edge-caching

Tenho uma curiosidade paralela em entender como a Zeit lida com DDOS e se é necessário colocar um Clouflare na frente: https://zeit.co/docs/v1/guides/how-to-use-cloudflare

Essa issue mexe diretamente com o comportamento da issue #5 sobre persistência dos dados e quando que eles devem ser atualizados. Talvez esse cache na ponta facilite tudo, pois a lógica da lamba pode ser algo como "atualizar sempre que retornar uma resposta sem erro do serviço que eu estou consultando" e deixa o cache na ponta ser o gargalo... quando expirar, entra na lambda.

API Bancos

Proposta Inicial

Lista com os bancos e seus dados.

GET /api/bancos

[
    {
        "codigo": "260",
        "nome": "Nu Pagamentos S.A.",
        "cnpj": "18236120000158",
        "ispb": "18236120", 
        "endereco": {
            "lougradouro": "R Capote Valente",
            "numero": "39",
            "complemento": "",
            "bairro": "Pinheiros",
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "05409000"
        },
        "site": "https://nubank.com.br/",
        "telefone": "08006086236"
    },
    {
        "codigo": "001",
        "nome": "Banco do Brasil S.A.",
        "cnpj": "00000000000191",
        "ispb": "00000000", 
        "endereco": {
            "lougradouro": "Saun Quadra 5 Bloco B Torre I 15O",
            "numero": "",
            "complemento": "Ed Banco do Brasil",
            "bairro": "Asa Norte",
            "municipio": "Brasilia",
            "uf": "DF",
            "cep": "70040912"
        },
        "site": "https://www.bb.com.br/",
        "telefone": "08007920001"
    },
    {
        ....
    }
]

GET /api/bancos/:codigo
/api/bancos/260

{
    "codigo": "260",
    "nome": "Nu Pagamentos S.A.",
    "cnpj": "18236120000158",
    "ispb": "18236120", 
    "endereco": {
        "lougradouro": "R Capote Valente",
        "numero": "39",
        "complemento": "",
        "bairro": "Pinheiros",
        "municipio": "Sao Paulo",
        "uf": "SP",
        "cep": "05409000"
    },
    "site": "https://nubank.com.br/",
    "telefone": "08006086236"
}

Código dos Municípios/Estados

Seria interessante se api de CEP retornasse os códigos do IBGE do Estado e município
(Código dos Municípios IBGE). Esses códigos são utilizados para na emissão de NF-e por exemplo ajudaria muito em vários sistemas de cadastro se ao coletar o endereço já fosse possível obter esses códigos.

Pelo que entendi os ceps na verdade não são obtidos por uma implementação nesse repositório, mas sim no modulo cep-promise, seria melhor implementar algo assim nesse modulo ou nesse repositório?

Bairros de uma cidade por CEP

Durante o desenvolvimento de um projeto pessoal, dei de cara com uma grande dificuldade em trabalhar com o sistema de CEPs, algumas cidades possuem apenas um CEP para tudo (Exemplo: a cidade de Paraty - 23970000) e alguns bairros pequenos não possuem CEP. Acredito que seria interessante retornar a lista de bairros de uma determinada cidade através da busca pelo CEP.

Guia de estilos

Sou novato aqui galera, to conhecendo o projeto agora e estou super disposto a contribuir no que estiver ao meu alcance.

Não conheço muito das funcionalidades do Next porém não vi nenhum arquivo de configuração de linting no projeto. Qual a opinião de vocês sobre isso ?

Creio que vale a pena configurar esses padrões de estilo de código, principalmente no inicio do projeto. Pois no futuro adicioná-los será bem mais trabalhoso.

Rotas para acesso aos índices do IBOVESPA

Existem alguns serviços que fornecem os índices dos papéis IBOVESPA, mas a maioria, se não todos são pagos. No entanto creio que essa é uma informação que deveria ser acessível a todos os tipos de investidores, desde investidores iniciantes até a grandes empresas.

Acho importante também levantar certos questionamentos:

  • A API pode ser disponibilizada em tempo real?
  • Limitação de requisições por período?
  • Disponibilização de webhooks para cadastro de eventos de preço?

Busca por Escolas

Olá pessoal, primeiramente gostaria de parabenizá-los pela iniciativa, com certeza com esta idéia vai ser possíveis criar coisas incríveis!

Gostaria de sugerir uma API que possibilita a busca por escolas por meio de diversos filtros: http://educacao.dadosabertosbr.com/api

Também queria tirar uma dúvida: as funcionalidades futuras poderam buscar dados de outras APIs, assim como de arquivos (datasets), tal como CSV, correto? Pergunto isso, pois existem muitos datasets no http://www.dados.gov.br/dataset e que poderiam ser úteis.

Valeu!

integração com metheora e IBGE

Além das integrações já realizadas conheço duas APIs que podem contribuir de forma relevante nesse projeto:

  • A API de localidades do IBGE que considero bastante completa com informações de mesorregiões, microrregião, distritos e subdistritos. Link abaixo
    https://servicodados.ibge.gov.br/api/docs/localidades?versao=1

  • Também há a API de endereços da metheora, Não possui tantos detalhes e algumas informações ainda estão faltando (como por exemplo nomes de bairros), mas acredito que mesmo assim possa contribuir para o projeto como redundancia para garantir que os dados estão corretos. Link abaixo
    http://enderecos.metheora.com/help

Lotericas API Free

Lotericas.io

Seguindo o mesmo motivo do projeto BrasilAPI, e também sou completamente contra pagar por ter dados públicos (todos os serviços de api que fornecem dados de lotericas são pagos WTF). Decidi criar a Lotericas.io que é uma API gratuita de resultados de loterias da caixa.

Acho que seria legal incluir essa api no BrasilAPI também.

Tecnologias usadas

  • Next.js.
  • Node.js e Puppeteer (captação dos dados no site da loterica).

Gits

Endpoint de dados climáticos

Fala, turma! Tudo certo?
Já que a proposta é ser uma aplicação que condensa vários endpoint úteis em uma coisa só, acredito que um endpoint para buscar previsão do tempo seja algo razoável de ser pensado.
Aqui o exemplo de uma API bacana para buscar por esse tipo de dado: HGBrasil

Busca de feriados nacionais

Fala pessoal,
Belezinha?

Seria legal ter no BrasilAPI um endpoint para obter informações de feriados de forma padão.
Pensando em algumas features com base em algo que já precisei desenvolver.

  • Feriados por região (municipio, estado, etc)
  • Quais os feriados endro de um intervalo de datas.
  • O feriado é nacional?
  • Facultativo?

Uma sugestão de campos de forma macro:

  • nome: nome do feriado
  • data: a data do feriado
  • descricao: descrição prévia contextualizando o feriado
  • tipo: se o feriado é nacional, estadual, ...
  • regiao: qual a região em que o feriado se aplica

Na época usei como base essa API do calendario que por sinal, me ajudou bastante.

Parabens pela iniciativa pessoal.

Sugestão de integração com cep.la

Olá. Tive problemas para encontrar o seguinte CEP na api: 11250-000. Este CEP foi encontrado na seguinte api: http://cep.la , porém meu servidor está hospedado em https e a api em um servidor http, logo não consigo fazer requisições para ele. Vim aqui para sugerir a integração pois esta api parece ter alguns CEPs que não são encontrados facilmente

Frontend para validar a aplicação

Sei que por tratar-se de uma API o frontend talvez não seja a BIGPICTURE aqui, mas acredito que alguns forms para o teste da plataforma dentro do site como propõe por exemplo uma outra api que faz captura de dados por CNPJ:
https://www.receitaws.com.br/api

Sejam fundamentais para validar a ideia por quem se propõe a utilizar, sem ter que gerar um enpoint no NPM para validar. (apesar de que isso já é muito bom)

Assim como a implementação da API em várias linguagens com a demonstração em código em cada uma das linguagens, como faz:
https://www.remove.bg/api

E o próprio Google na sua documentação do GCP:
https://cloud.google.com/datastore/docs/concepts/queries

Testar PRs com E2E

Uma das coisas que devemos aproveitar por conta de usar o Now é fazer testes E2E de uma forma fácil e rápida.

Já instalei o hook que a cada PR ele cria uma URL única (e quando é feito o merge na master) automaticamente faz o deploy para o alias principal brasilapi.com.br.

A questão é: como fazemos esse teste E2E? É contra um próprio localhost:3000 dentro da suite de testes ou usando a URL real criada pela Zeit para aquela branch?

Se eu não me engano, ele cria uma URL "fixa" com o nome da branch, talvez isso ajude (ou não).

Graphql

Olá, eu gostei bastante do projeto e acho que tem um grande futuro de varias outras funcionalidades.

Eu estava olhando o fonte e tive a ideia de disponibilizar um endpoint para requisições graphql.

Pensei em uma estrutura mais escalavel, que cada "serviço/endpoint" define suas typeDefs e resolvers e o endpoint raiz disponibiliza na rota

Buscar polígono por [Estados|Cidades|Bairros]

E ai! Parabéns pela iniciativa, excelente projeto!

Esses dias me deparei com a seguinte questão: "Se teríamos como pegar os polígono dos bairros de alguma cidade?"

Único serviço que encontrei de "forma aberta" com os bairros "desenhados" foi do Wikimapia

Até consegui esses valores... de uma forma simples digamos assim.

Acreditam ser relevante para esse projeto?
Valeu!

Rota para rastreio de encomendas

Olá! Parabéns pela iniciativa, excelente projeto!

Creio ser relevante uma rota para obter as informações dos rastreios de encomendas. A API SRO segue uma estrutura semelhante a de busca por CEP, limitando acesso CORS.

Poderia utilizar esse pacote: tracking-correios. Várias issues foram criadas com o mesmo assunto: limitação de CORS para utilizar pelo navegador.

Cache longo talvez não seja tão relevante nesse caso específico, pois os dados alteram com uma frequência bem maior que CEPs.

Acreditam ser relevante para esse projeto?
Valeu!

[Feature] API de consulta de instituições bancárias brasileiras

Descrição

Seria interessante ter uma api que lista e descreve os dados das instituições financeiras no Brasil.
Isso é extremamente necessária para fintechs fazer operações financeiras e acredito que seria de grande ajuda pra várias pessoas! 😬

Uma estrutura interessante que estava pensando era:

{
  "ispb_code": "00000000",
  "name": "Banco do Brasil S.A.",
  "number_code": "001",
  "short_name": "BCO DO BRASIL S.A."
}

Assim como a rota de CEP os dados nessa base se alteram bem pouco e seria possível utilizar cache agressivo para manter tudo nas bordas da CDN por ao menos 24h.

Utilização de Containers

Olá, gostei bastante do projeto e gostaria de contribuir o máximo que conseguir :)

Notei que, hoje, não temos a garantia de um mesmo ambiente (desenvolvimento/produção/etc) para todos. Dito isto, por que não deixar todos no mesmo "nível" utilizando o nosso querido Docker?

O que acham desta proposta?

API de consulta da tabela FIPE

Já que estamos falando em Brasil e dados públicos, que tal adicionar rotas de consulta à Tabela FIPE.
Sei que já existe muitas API e lugares para consulta desses dados, mas seria mais uma rota bem útil para este projeto.

Fachada e agregador de dados como Dados Abertos e Portal Transparência

Seria interessante, afim de trazer à sociedade uma visão mais transparente, e livre de conceitos técnicos do mundo político, o panorama geral de cada um dos deputados eleitos. Informações como:

  1. Gastos parlamentares de uma forma bem simples de entender;
  2. Últimos projetos em que o deputado se mostrou a favor ou contra;
  3. Ter um feed de notícias a respeito de cada um desses deputados;
  4. Alimentar um repositório (instagram ou facebook) com as informações mais quentes desse mundo político.

Links:

Portal Transparência - Despesas
Dados Abertos - Swagger

Buscas por informações em tempo real sobre frota de ônibus por cidade

Basicamente, poderíamos agregar no BrasilAPI endpoints referente informações em tempo real sobre transportes públicos, bem como informações de previsibilidade e quais opções de rotas para um determinado destino. Poderíamos começar pela principais cidades do Brasil ou com cidades que fornecem serviços de rastreamento e planejamento de suas frotas.

Design + Marketing + layout

Olá amigos, estive a ver sobre este projeto no YouTube e acredito muito no potencial do mesmo. Sou designer e tenho já 5 anos focados só em UX/UI e gostaria muito de contribuir a este projeto.

Os tópicos iniciais que eu gostaria de discutir com vocês são:

Sobre a marca: Já foi feita uma estratégia de branding para ela?
Sobre o site: Como o site vai entregar a informação aos utilizadores? Vamos apresentar uma wiki ou vamos criar algo que seja fora do padrão? Algo que surpreenda nossa equipe?
Leads Como vamos nos relacionar com os com as pessoas que irão utilizar a plataforma? Vamos trabalhar alguma estratégia de nutrição de leads para fortalecer a comunidade?

Para ser bem sincero tem muito mais perguntas, mas vamos por partes. Aguardo o vosso retorno.

AAAAA 😍

Pooouts mano, que irado!!!
Ta mto lindo isso, NOW é mto delicinha! 😱

Poxaaan o Github tinha que ter um chat pra gente trocar ideias sobre isso 😢

Incluir o Shields no readme

Olá,

Eu gostaria de sugerir para colocar o shields como de testes e2e (entre outros) no readme, é uma alteração simples e que passa confiança e o feedback dos testes. Se aprovarem eu posso fazer essa alteração.

Grato,
Flávio

Distância entre Cep's

Hoje me deparei com um problema.. e talvez seja do interesse de mais alguém criar uma solução.
Que tal criar um endpoint que retorne a Distância entre dois Ceps?

Persistência dos dados

Isso é uma coisa interessante para resolver, pois tem várias abordagens dependendo de como o projeto vai crescer, por exemplo:

Abordagem 1

Cada sub projeto (tipo consulta de cep) tem sua própria tabela para guardar os ceps.

Abordagem 2

Uma única tabela genérica de cache, que possui uma chave, a informação que deve ser guardada (em JSON) e uma outra coluna para tempo de expiração.

E estamos bastante dispostos a testar o FaubaDB.

Padrão de commit messages

@lucianopf o que acha de ser tão simples quanto:

  1. Commits em inglês (ou em português já que podemos fazer os PRs em português?)
  2. [category]: [message] por exemplo do seu último PR: cdn: add Zeit smart cache in cep service

E por hora sinta-se livre em fazer merge direto @lucianopf vamos entortar/desentortar o código como quisermos nesse momento 👍

Versionamento dos endpoints

Isso é uma questão extremamente importante... como lidar com a evolução da interface pública e as breaking changes?

Num módulo gerenciado pelo NPM isso é super fácil, a gestão pelo lado de quem consome isso já vem de graça por conta de como o NPM lida com semantic versioning... agora, como fazer numa rota pública que inclusive não pode ter versionamento gerenciado por uma conta/perfil como é feito em casos como Pagar.me e Stripe, dado que não teremos esse conceito de conta?

Ótima notícia: Vercel vai ser sponsor do projeto 😍

Primeiro, não dá para imaginar que esse projeto esta quase chegando em 1mil stars, simplesmente sensacional o engajamento da turma! 🤩

E agora que eu consegui soltar a série de 3 vídeos sobre desenvolvimento web, os conteúdos no canal vão retomar a quantidade de produção normal e estou louco para voltar a colocar a mão na massa aqui no repositório junto com todos vocês, pois tem muitas Issues e Pull Requests importantes precisando de atenção. O @lucianopf também vai profissionalizar algumas partes, tanto que sentimos a necessidade de tirar o projeto de uma conta hobby minha para um team dentro da Vercel e a boa notícia vem exatamente ai:

Nós nos aplicamos para o programa de apoio a projetos Open Source da Vercel e fomos aceitos!!! 😍

Muito obrigado especialmente ao @paulogdm por tudo o que já fez no projeto e por atender esse caso.

O projeto já foi migrado da minha conta pessoal para conta de time e o processo foi muito tranquilo, inclusive reapontar o domínio (deu para fazer tudo por dentro da Dashboard, sem precisar mexer em DNS). O bom disso é que as modificações foram aplicadas imediatamente.

E para o sponsor deles vamos adicionar alguns banners da Vercel (tanto na página quanto no repositório) identificando que o projeto está recebendo o apoio deles e eu devo fazer isso até amanhã e nisso também tem uma outra boa notícia:

Agora o projeto tem um logo 😍 (ou pelo menos, uma versão 0.0.1-alpha de um logo 😂)

E é inspirado na proporção de Fibonacci, o que eu pessoalmente acho uma delicinha e na minha visão é a definição máxima de "ordem e progresso" 👍

New Project (1)

E como o @lucianopf apontou, o logo também sinaliza a natureza de componentes do projeto, em que foi componentizado até a versão de cada API. Massinha né?

Bom, eu preciso gravar um vídeo para o canal daqui a pouco, mas em seguida eu já quero colocar essas coisas no ar 🤝 vamo que vamo turma!!!! 😍

REST API versioning

Olá. Acabei de conhecer o projeto e vi que já houve uma discussão sobre versionamento #12 que levou ao PR #25. Apesar de não existir uma forma correta de se fazer versionamento[1], gostaria de propor um modelo diferente que acho que seria mais vantajoso para esse projeto.

Contexto

Levando em conta que esse projeto criará uma API pública que potencialmente será utilizada por diversos clientes, acredito que é de extrema importância manter o processo de desenvolvimento o mais eficiente possível. Em minha experiência, resource versioning ou global uri versioning adicionam algumas complexidades no desenvolvimento da API que acabam desacelerando a sua evolução:

  • Manutenção: breaking changes normalmente levam a criação de outro endpoint, o que leva a manutenção de duas ou mais implementações distintas (no caso de múltiplas versões) além do planejamento paralelo para descontinuar cada versão. Imaginem como será para resolver bugs que afetam múltiplas versões por exemplo.
  • Obriga atualização nos clientes: Esse modelo de versionamento normalmente adiciona mais trabalho para os clientes se manterem atualizados.
  • Pessoalmente eu também acho que URI versioning tira um pouco o charme de uma REST(ful) API já que não considero a versão um recurso ou sub-recurso. Lembrando que o pilar de uma REST API são os recursos e as operações que posso fazer nos mesmos.

Proposta

Manter a URI consistente (sem versão) e utilizar content negotiation (utilizando Accepts e Content-Type headers) para negociar qual conteúdo o cliente precisa. Em outras palavras, negociar a versão. Na prática a API evoluiria mantendo compatibilidade com as versões anteriores e os endpoints seriam os mesmos. Essa abordagem é utilizada no ambiente empresarial[2 e 3].

Mas enfim, como seria isso na prática?

Antes:

GET /api/v1/cep/[cep]

Depois:

# O serviço é uma API (e nada mais). Não vejo necessidade de adicionar /api na URI, mas não tenho nada contra
/cep/:id

Guidelines

Considerando o Pull Request #101 e Issue #14 , teríamos os seguintes guidelines:

Usar semantic versioning v2

OpenAPI permite adicionar a versão em #/info/version (recomendo não usar as regras 9 e 10). Exemplo:

openapi: 3.0.1
info:
    title: CEP API
    description: API for <...>
    version: 1.3.7
    <...>

Apesar de não ter um impacto direto no funcionamento da API, esses metadados dão visibilidade e informações sobre a API para os clientes.

Usar media type versioning

Versionamento baseado em negociação de conteúdo reduz o acoplamento e facilita a evolução da API. A versão (ou conteúdo) são negociados usando o cabeçalho Content-Type e Accept do protocolo HTTP. Por exemplo: application/brasil.cep+json;version=2. Para manter compatibilidade, cada breaking change (major release) cria um novo tipo (media type). Assim, os recursos (URI) e a semântica das operações são mantidas enquanto o versionamento é limitado ao tipo de conteúdo.

Teríamos as seguintes regras:

  • Usar media types personalizados para versões diferentes. No jargão de semantic release seria criar um novo media type quando tivermos um major release. Enquanto não tivermos nenhuma mudança de versão é melhor se manter utilizando o padrão: application/json
  • Incluir versões no cabeçalho do request e response para dar visibilidade
  • Incluir Content-Type no cabeçalho Vary para permitir cache de versões diferentes em qualquer proxy que esteja no caminho:
    Vary: Content-Type
    

Formato / esquema:

application/<custom-media-type>+json;version=<version>
  • custom-media-type é o recurso. Exemplo: brasil.cep
  • version é a versão. Exemplo: 2

Exemplo

Suponha que o cliente queira apenas a nova versão:

Accept: application/brasil.ce+json;version=2

Um servidor deve responder, assim como um cliente enviando uma requisição com conteúdo (POST por exemplo), usando o cabeçalho Content-Type do protocolo HTTP para declarar explicitamente qual versão do conteúdo esta sendo enviada:

Content-Type: application/brasil.cep+json;version=2

Próximos passos

Definir regras/guidelines para os demais pontos não comentados: metadados, segurança, compatibilidade, desativação de endpoints (como se traduz deprecation para pt-br?), performance, semântica das operações, cabeçalhos utilizados, etc.

Referências (infelizmente não conheço muito material em português)

  1. API Versioning Has No "Right Way"
  2. Enterprise Integration Using REST
  3. Zalando RESTful API Guidelines
  4. Evolving HTTP APIS

Busca CNPJ

Olá Pessoal, essa é uma das minhas primeiras Issues no github, então desculpe se cometer algum erro. Programação para mim é um hobbie, já que atuo como Engenheiro Civil.

Vamos ao que interessa, acredito que a API tenha um proposito de produtividade no final das contas, não só para o programador mas também para o usuário que utilizar o sistema. E para mim sempre foi uma coisa muito chata cadastrar empresas. E a chateação aumenta, quando vai no site da receita e digita o CNPJ e todos dados aparecem (não sei se eles liberam alguma API, nunca consegui achar nada), então acho que seria algo útil uma implementação onde digita o CNPJ e os dados principais são retornados.

Ah e parabéns pela iniciativa, vou tentar ajudar também. Bom que me ajuda nos meus estudos de javascript e nodeJS.

Tábua de marés

Poderiamos aproveitar o desenvolvimento dessa API, e adicionar um endpoint para obter os dados das tábuas das marés de uma determinada região, atualmente é necessário ter um código para ler o PDF que a marinha fornece em seu site.

Buscar CEP pelo logradouro

Olá!

Parabéns pela iniciativa!! Gostaria de sugerir um endpoint para retornar os possíveis CEP informando um logradouro.

image

image

Coordenadas pelo o CEP

Acredito que agregaria muito valor adicionar a funcionalidade retornar as coordenadas dado o input de um cep.

Segue abaixo um projeto que já tenta resolver esse problema:

coordenadas-do-cep:
Github
NPM

Transformar em api, mas o que?

Vamos transformar o Brasil em uma API?

Pela chamada do projeto, fiquei imaginando que tipos de APIs seriam essas?

Como sugestão, seria interessante colocar quais APIs estariam no escopo do projeto ou não (mesmo que não implementadas) visto que hoje só existe a de CEP, ou até uma issue pontuando quais fariam sentido existir aqui.

Abraço!

Sugestão de design do layout ( figma )

Português

olá ✋! eu fiz um pequeno design de como o site poderia ser ( pelo menos a parte da apresentação da API ).
Fiquem a vontade pra alterar e deixar o design no melhor estilo possivel.

link do figma com o design
https://www.figma.com/file/toXC8uf52k7TGDAdJ2vXdd/brasilAPI?node-id=0%3A1

English

Hey ✋! i made this design, kinda thinking of how the website's final design could be ( at least the API's presentation ).
Feel free to change the design, to let it be the best as possible!

link on figma
https://www.figma.com/file/toXC8uf52k7TGDAdJ2vXdd/brasilAPI?node-id=0%3A1

Preço e prazo de fretes pelos correios

Seguindo a ideia e problemática apresentada no readme:

Acesso programático de informações é algo fundamental na comunicação entre sistemas mas, para nossa surpresa, uma informação tão útil e pública quanto um CEP não consegue ser acessada diretamente por um navegador por conta da API dos Correios não possuir CORS habilitado.

Uma das funções que pessoalmente precisei implementar no servidor, uma vez que conforme dito não conseguimos acessar direto do navegador, é a função retorno do valor de frete, dado o cep de origiem, o cep de destino, e mais algumas informações do produto.

Links:

Preços e prazos Correios

Quais os objetivos reais do projeto?

Olá, quando vi o título de "Vamos transformar o Brasil em uma API?" achei algo bem amplo, porém com muito potencial e que me deixou entusiasmado em colaborar. Mas ao ler o README e as issues fiquei um pouco perdido, aparentemente o único endpoint implementado foi o de busca de CEPs, que basicamente faz uma chamada da API do cep-promise. Sendo esse endpoint o único citado no README do projeto. Então ficaram alguns questionamentos na minha cabeça:

  1. Quais são os reais objetivos do projeto?
  2. O que seria "transformar o Brasil em uma API"?
  3. Existe um roadmap?
  4. Será que essas informações não deveriam estar mais acessíveis?

Brasil.IO (e evitar retrabalho)

Oi, pessoal, tudo bem?
Criei o Brasil.IO há alguns anos com objetivos bem parecidos com o desse projeto e estou criando essa issue para abrir um canal de comunicação com a finalidade de evitar retrabalho: o Brasil.IO já possui uma infraestrutura de hospedagem de datasets (ainda precisamos melhorar algumas coisas, mas já existe e está funcional), já possui diversos voluntários contribuindo com código e dinheiro para manter os servidores e já é utilizado por muita gente (incluindo grandes veículos de mídia).

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.