barbaraport/address-consultation-api

Source code for the Java Developer Challenge

🏡 Address-Consultation-API 🏡

Source code for the Java Developer Challenge, which consists from building an API to send a zip code and retrieve its address, if the zip code exists.

💻 Functional requirements 🖱️

The following requirements can directly affect the user experience and must be considered when handling errors.

✔️ The sent zip code can have a mask or not

       ✔️ Check if the zip cod mask matches to the brazilian zip code pattern

✔️ In case of failure from the external API (Via Cep API), return an informative message

       ✔️ Valid zip code, but nonexistent (example: 99999999)

✔️ In case of failure from the consultation API, return an informative message

       ✔️ Validation for digits quantity (example: "950100100")

       ✔️ Validation for alphanumeric digits (example: "95010A10")

       ✔️ Validation for spaces (example: "95010 10")

✔️ Calculate the fare according to the zip code zone

🔗 Desired API ⚙️

POST /v1/consulta-endereco

The request body must have an object containing the CEP property.

{
    "cep": "01001000"
}

Response 200

If the sent zip code is valid, then the address will be returned and the response status code will be 200.

{
    "cep": "01001-000",
    "rua": "Praça da Sé",
    "complemento": "lado ímpar",
    "bairro": "Sé",
    "cidade": "São Paulo",
    "estado": "SP",
    "frete": 7.85
}

Response 400

If the sent zip code is not valid or is nonexistent, then the response body will contain a message and the response status code will be 400.

{
    "message": "The zip code cannot be empty."
}

🛠️ Non-functional requirements 🧰

The following requirements do not directly affect the user experience, but are part of the technical requirements to compose the infrastructure and quality of the project.

✔️ Java 11

✔️ Spring Boot

✔️ API REST Template

✔️ Swagger Documentation

✔️ JUnit5 unity testing

✔️ Cucumber automated tests

🏃 Running the project 🏃‍♀️

To run the project successfully follow the steps below:

⬇️ Clone the project

To clone the entire source code to run the project, type:

git clone https://github.com/barbaraport/address-consultation-api.git

✔️ Run the tests ✔️

1. Be sure that you already have Java 11 installed and configured;
2. Open the project folder in the terminal;
3. Execute all tests (from JUnit and Cucumber), typing:

.\mvnw test

Start the application ⬆️

To execute the server application, type:

.\mvnw spring-boot:run

📚 Access the Swagger UI

If you want to see the API documentation, access the Swagger UI clicking here or acessing it via the URL http://localhost:8080/swagger-ui.html

⚠️ Be sure that the server application is running! ⚠️