Skip to content

Commit 1afed48

Browse files
ceelsoinceelsoin
committed
docs: Update README to clarify API usage and remove outdated sections
1 parent 9393f7c commit 1afed48

1 file changed

Lines changed: 96 additions & 94 deletions

File tree

‎README.md‎

Lines changed: 96 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,18 @@
44

55
<a href="https://github.com/brasilcep/brasilcep-webservice/actions/workflows/cicd.yml"><img src="https://github.com/brasilcep/brasilcep-webservice/actions/workflows/cicd.yml/badge.svg" /></a>
66

7-
API REST para consulta de CEPs brasileiros, baseada na base oficial dos Correios (DNE). Projeto open source, rápido, eficiente e fácil de usar.
7+
API REST para consulta de CEPs brasileiros, baseada na base oficial dos Correios (DNE) com propósito de hospedar no seu servidor sem necessidade de acesso a terceiros.
8+
9+
Projeto open source, rápido, eficiente e fácil de usar.
810

911
## Sumário
1012
- [Sumário](#sumário)
1113
- [Como rodar](#como-rodar)
1214
- [Build local](#build-local)
1315
- [Configurações via ENV](#configurações-via-env)
1416
- [Importação da base DNE](#importação-da-base-dne)
17+
- [Modo seed: importação da base DNE](#modo-seed-importação-da-base-dne)
18+
- [Estrutura de pastas esperada para a base DNE](#estrutura-de-pastas-esperada-para-a-base-dne)
1519
- [Endpoints da API](#endpoints-da-api)
1620
- [`GET /cep/:cep`](#get-cepcep)
1721
- [`GET /healthcheck`](#get-healthcheck)
@@ -21,8 +25,6 @@ API REST para consulta de CEPs brasileiros, baseada na base oficial dos Correios
2125
- [Configurações da API](#configurações-da-api)
2226
- [Licença](#licença)
2327
- [Contribua](#contribua)
24-
- [Modo populate: importação da base DNE](#modo-populate-importação-da-base-dne)
25-
- [Estrutura de pastas esperada para a base DNE](#estrutura-de-pastas-esperada-para-a-base-dne)
2628

2729
---
2830

@@ -57,27 +59,30 @@ O binário será gerado em `./bin/brasilcep-webservice`.
5759

5860
## Configurações via ENV
5961

60-
Todas as configurações podem ser definidas via variáveis de ambiente. Use o formato abaixo:
61-
62-
| ENV_VAR | Valor padrão | Descrição |
63-
|--------------------------------------|----------------------|---------------------------------------------------------------------------|
64-
| MODE | listen | Modo de operação ("listen" para API HTTP) |
65-
| API_PORT | 8080 | Porta HTTP para escutar |
66-
| API_PROMETHEUS_ENABLE | true | Habilita métricas Prometheus |
67-
| API_ENABLE_GZIP | true | Habilita compressão Gzip |
68-
| API_GZIP_COMPRESSION_LEVEL | 5 | Nível de compressão Gzip (1-9) |
69-
| API_RATE_LIMIT_ENABLE | true | Habilita rate limiting |
70-
| API_RATE_LIMIT_MAX_ALLOWED_REQUESTS_PER_WINDOW | 100 | Máximo de requisições por janela de tempo |
71-
| API_RATE_LIMIT_REQUESTS_BURST | 20 | Burst de requisições permitidas |
72-
| API_RATE_LIMIT_EXPIRE_MINUTES | 15 | Janela de tempo do rate limit (minutos) |
73-
| API_CORS_ALLOW_ORIGINS | * | Origens permitidas no CORS (array, ex: ["*"]) |
74-
| API_CORS_ALLOW_METHODS | GET,HEAD,PUT,PATCH,POST,DELETE | Métodos permitidos no CORS (array) |
75-
| API_CORS_ALLOW_HEADERS | Origin,Content-Type,Accept,Authorization | Headers permitidos no CORS (array) |
76-
| DB_PATH | ./data | Caminho para os arquivos do banco BadgerDB |
77-
| DB_RAW_PATH | ./dne | Caminho para os arquivos originais do DNE |
78-
| LOG_FORMAT | json | Formato do log ("json" ou "text") |
79-
| LOG_LEVEL | info | Nível de log ("debug", "info", "warn", "error") |
80-
62+
Todas as configurações podem ser definidas via variáveis de ambiente:
63+
64+
- **MODE**: Modo de operação ("listen" para API HTTP ou "seed" para popular dados do DNE na base). Padrão: `listen`
65+
- **API_PORT**: Porta HTTP para escutar. Padrão: `8080`
66+
67+
- **API_PROMETHEUS_ENABLE**: Habilita métricas Prometheus. Padrão: `true`
68+
69+
- **API_ENABLE_GZIP**: Habilita compressão Gzip. Padrão: `true`
70+
- **API_GZIP_COMPRESSION_LEVEL**: Nível de compressão Gzip (1-9). Padrão: `5`
71+
72+
- **API_RATE_LIMIT_ENABLE**: Habilita rate limiting. Padrão: `true`
73+
- **API_RATE_LIMIT_MAX_ALLOWED_REQUESTS_PER_WINDOW**: Máximo de requisições por janela de tempo. Padrão: `100`
74+
- **API_RATE_LIMIT_REQUESTS_BURST**: Burst de requisições permitidas. Padrão: `20`
75+
- **API_RATE_LIMIT_EXPIRE_MINUTES**: Janela de tempo do rate limit (minutos). Padrão: `15`
76+
77+
- **API_CORS_ALLOW_ORIGINS**: Origens permitidas no CORS (array, ex: ["*"]). Padrão: `*`
78+
- **API_CORS_ALLOW_METHODS**: Métodos permitidos no CORS (array). Padrão: `GET,HEAD,PUT,PATCH,POST,DELETE`
79+
- **API_CORS_ALLOW_HEADERS**: Headers permitidos no CORS (array). Padrão: `Origin,Content-Type,Accept,Authorization`
80+
81+
- **DB_PATH**: Caminho para os arquivos do banco BadgerDB. Padrão: `./data`
82+
- **DB_RAW_PATH**: Caminho para os arquivos originais do DNE. Padrão: `./dne`
83+
84+
- **LOG_FORMAT**: Formato do log ("json" ou "text"). Padrão: `json`
85+
- **LOG_LEVEL**: Nível de log ("debug", "info", "warn", "error"). Padrão: `info`
8186
Exemplo de uso:
8287
```sh
8388
export API_PORT=8081
@@ -94,10 +99,7 @@ Para importar a base oficial dos Correios (DNE):
9499
zipImporter := zipcodes.NewZipCodeImporter(logger)
95100
zipImporter.PopulateZipcodes("./dne")
96101
```
97-
Ou execute o modo cliente da aplicação executando o modo populate
98-
```bash
99-
MODE=populate go run main.go
100-
```
102+
Ou execute o modo seed
101103

102104
Arquivos necessários:
103105
- LOG_LOCALIDADE.TXT
@@ -107,6 +109,71 @@ Arquivos necessários:
107109
- LOG_UNID_OPER.TXT
108110
- LOG_CPC.TXT
109111

112+
## Modo seed: importação da base DNE
113+
114+
O modo `seed` serve para importar a base oficial dos Correios (DNE) para o banco local BadgerDB. Basta definir a variável de ambiente `MODE=seed` e executar o projeto:
115+
116+
```sh
117+
export MODE=seed
118+
go run main.go
119+
```
120+
Ou via Makefile:
121+
```sh
122+
MODE=seed make run
123+
```
124+
125+
O caminho da base DNE pode ser configurado via `DB_RAW_PATH` (por padrão, `./dne`).
126+
127+
O importador lê todos os arquivos TXT necessários e popula o banco local. Após o término, o modo pode ser alterado para `listen` para servir a API normalmente.
128+
129+
### Estrutura de pastas esperada para a base DNE
130+
131+
Coloque todos os arquivos TXT do DNE na pasta definida por `DB_RAW_PATH` (por padrão, `./dne`).
132+
133+
Exemplo:
134+
```
135+
./
136+
├── main.go
137+
├── dne/
138+
│ ├── LOG_LOCALIDADE.TXT
139+
│ ├── LOG_BAIRRO.TXT
140+
│ ├── LOG_LOGRADOURO_AC.TXT
141+
│ ├── LOG_LOGRADOURO_AL.TXT
142+
│ ├── LOG_LOGRADOURO_AM.TXT
143+
│ ├── LOG_LOGRADOURO_AP.TXT
144+
│ ├── LOG_LOGRADOURO_BA.TXT
145+
│ ├── LOG_LOGRADOURO_CE.TXT
146+
│ ├── LOG_LOGRADOURO_DF.TXT
147+
│ ├── LOG_LOGRADOURO_ES.TXT
148+
│ ├── LOG_LOGRADOURO_GO.TXT
149+
│ ├── LOG_LOGRADOURO_MA.TXT
150+
│ ├── LOG_LOGRADOURO_MG.TXT
151+
│ ├── LOG_LOGRADOURO_MS.TXT
152+
│ ├── LOG_LOGRADOURO_MT.TXT
153+
│ ├── LOG_LOGRADOURO_PA.TXT
154+
│ ├── LOG_LOGRADOURO_PB.TXT
155+
│ ├── LOG_LOGRADOURO_PE.TXT
156+
│ ├── LOG_LOGRADOURO_PI.TXT
157+
│ ├── LOG_LOGRADOURO_PR.TXT
158+
│ ├── LOG_LOGRADOURO_RJ.TXT
159+
│ ├── LOG_LOGRADOURO_RN.TXT
160+
│ ├── LOG_LOGRADOURO_RO.TXT
161+
│ ├── LOG_LOGRADOURO_RR.TXT
162+
│ ├── LOG_LOGRADOURO_RS.TXT
163+
│ ├── LOG_LOGRADOURO_SC.TXT
164+
│ ├── LOG_LOGRADOURO_SE.TXT
165+
│ ├── LOG_LOGRADOURO_SP.TXT
166+
│ ├── LOG_LOGRADOURO_TO.TXT
167+
│ ├── LOG_GRANDE_USUARIO.TXT
168+
│ ├── LOG_UNID_OPER.TXT
169+
│ ├── LOG_CPC.TXT
170+
│ └── LOG_LOCALIDADE.TXT
171+
```
172+
173+
**Atenção:** Todos os arquivos devem estar codificados em ISO-8859-1, conforme padrão dos Correios.
174+
175+
Após importar, rode o projeto normalmente em modo `listen` para servir a API.
176+
110177
## Endpoints da API
111178
112179
### `GET /cep/:cep`
@@ -203,69 +270,4 @@ Estatísticas dos CEPs por UF.
203270
MIT
204271
205272
## Contribua
206-
Pull requests são bem-vindos! Abra issues para sugestões ou problemas.
207-
208-
## Modo populate: importação da base DNE
209-
210-
O modo `populate` serve para importar a base oficial dos Correios (DNE) para o banco local BadgerDB. Basta definir a variável de ambiente `MODE=populate` e executar o projeto:
211-
212-
```sh
213-
export MODE=populate
214-
go run main.go
215-
```
216-
Ou via Makefile:
217-
```sh
218-
MODE=populate make run
219-
```
220-
221-
O caminho da base DNE pode ser configurado via `DB_RAW_PATH` (por padrão, `./dne`).
222-
223-
O importador lê todos os arquivos TXT necessários e popula o banco local. Após o término, o modo pode ser alterado para `listen` para servir a API normalmente.
224-
225-
### Estrutura de pastas esperada para a base DNE
226-
227-
Coloque todos os arquivos TXT do DNE na pasta definida por `DB_RAW_PATH` (por padrão, `./dne`).
228-
229-
Exemplo:
230-
```
231-
./
232-
├── main.go
233-
├── dne/
234-
│ ├── LOG_LOCALIDADE.TXT
235-
│ ├── LOG_BAIRRO.TXT
236-
│ ├── LOG_LOGRADOURO_AC.TXT
237-
│ ├── LOG_LOGRADOURO_AL.TXT
238-
│ ├── LOG_LOGRADOURO_AM.TXT
239-
│ ├── LOG_LOGRADOURO_AP.TXT
240-
│ ├── LOG_LOGRADOURO_BA.TXT
241-
│ ├── LOG_LOGRADOURO_CE.TXT
242-
│ ├── LOG_LOGRADOURO_DF.TXT
243-
│ ├── LOG_LOGRADOURO_ES.TXT
244-
│ ├── LOG_LOGRADOURO_GO.TXT
245-
│ ├── LOG_LOGRADOURO_MA.TXT
246-
│ ├── LOG_LOGRADOURO_MG.TXT
247-
│ ├── LOG_LOGRADOURO_MS.TXT
248-
│ ├── LOG_LOGRADOURO_MT.TXT
249-
│ ├── LOG_LOGRADOURO_PA.TXT
250-
│ ├── LOG_LOGRADOURO_PB.TXT
251-
│ ├── LOG_LOGRADOURO_PE.TXT
252-
│ ├── LOG_LOGRADOURO_PI.TXT
253-
│ ├── LOG_LOGRADOURO_PR.TXT
254-
│ ├── LOG_LOGRADOURO_RJ.TXT
255-
│ ├── LOG_LOGRADOURO_RN.TXT
256-
│ ├── LOG_LOGRADOURO_RO.TXT
257-
│ ├── LOG_LOGRADOURO_RR.TXT
258-
│ ├── LOG_LOGRADOURO_RS.TXT
259-
│ ├── LOG_LOGRADOURO_SC.TXT
260-
│ ├── LOG_LOGRADOURO_SE.TXT
261-
│ ├── LOG_LOGRADOURO_SP.TXT
262-
│ ├── LOG_LOGRADOURO_TO.TXT
263-
│ ├── LOG_GRANDE_USUARIO.TXT
264-
│ ├── LOG_UNID_OPER.TXT
265-
│ ├── LOG_CPC.TXT
266-
│ └── LOG_LOCALIDADE.TXT
267-
```
268-
269-
**Atenção:** Todos os arquivos devem estar codificados em ISO-8859-1, conforme padrão dos Correios.
270-
271-
Após importar, rode o projeto normalmente em modo `listen` para servir a API.
273+
Pull requests são bem-vindos! Abra issues para sugestões ou problemas.

0 commit comments

Comments
 (0)