It's a simple API for a bank, this API the user can create a register, using CPF(is a unique brazilian ID) and PASSWORD, if the user create a complete account the API will return a unique code with 8 digits, this code can be used by the other users in register, this is called referral code. Case the user put incomplete data will take a status incomplete and will not return the code.
All the user sensitive data will be encrypted in database, the encryption use AES.GCM algorithm, for password use the Argon2 algorithm. To use this function we must have a enviroment variable setted, called CLOAK_KEY. In Run in your local enviroment section you can see with more details.
If user need complete the register, will ask user and password. This user and password is the CPF and Password registered before.
The API can list all referrals of one user too, but this need the Authentication.
This explain simple how the User Create user works, if the register status is complete will return a code and if is pending this code will not be returned.
This show the flow to update a existing user. Need the authentication to make this requests.
Simple flow how the get referrals works. Need be authorized to make this request.
This API only have two end points.
This is in the same end point of update user. Don't need authentication to create, but for update yes. The endpoint is describe above:
POST ${url_base}/api/user
This need receive a body param, like described below:
This is a complete register data, the API will return this:
(HTTP response code 201)
{
"message": "User register complete",
"user": {
"birth_date": "1990-01-01",
"city": "São Paulo",
"country": "Brasil",
"cpf": "12345678935",
"email": "[email protected]",
"gender": null,
"id": "481a2990-2f48-41bb-9b95-2eadc80c18bb", //User id
"name": "User Name",
"referral_code": null,
"state": "Paraná",
"status": "complete", //User register status
"user_code": "GstLTGAs" //8 digit unique user code, used to referral
}
}If send part of data we have a return like that:
(HTTP response code 201)
{
"message": "User register pending",
"user": {
"birth_date": null,
"city": null,
"country": null,
"cpf": "12345678935",
"email": null,
"gender": null,
"id": "e756f112-138f-4553-8cc2-f1131c500cb9",
//User id
"name": null,
"referral_code": null,
"state": null,
"status": "pending" //Status now is pending
}
}Note the user stuatus now is pending and doesn't have a user_code.
Users pending can not be referrals, so can't see the referrals in Get Referrals end point.
The Authentication is a Basic HTTP Authentication, responding like the documentation of MDN.
To make this authentication just need put CPF and Password in Authentication Header like below:
Basic <Base64 encoded CPF and Password>
Case try make an operation unauthorized the API will return:
(HTTP response code 401)
{
"message": {
"error": "Insert user and password"
}
}Case try make an operation with a wrong user the API will return:
(HTTP response code 401)
{
"message": {
"error": "User not found"
}
}Case try make an operation with a invalid password:
(HTTP response code 401)
{
"message": {
"error": "invalid password"
}
}Case try make an operation with another user the API will return:
(HTTP response code 403)
{
"message": {
"error": "Do not have permission"
}
}Update user use the same end point of create, but now we need Authorize our user. So the responses is the same.
This end point we can see all referrals of one user, but now we need Authorize our user.
GET ${url_base}/api/user/{user_code}/referrals
If the authorization is ok and user have referrals, the API will respond this:
{
"message": "Listing all referrals",
"referrals": [
{
"id": "1f565a27-e02a-4025-be61-83a1ecf62b9f", //ID of the user who used the code
"name": "Friend Name" //Name of user who used the code
}
]
}If the authorization is ok and user don't have referrals, the API will respond this:
{
"message": {
"error": "User has no referrals"
}
}The server is running in a Gigalixir instance, can be found in:
https://bankapidep.gigalixirapp.com/
This is build automated using github actions.
This is a open-source project so anyone can contribuite, just follow our rules and this instructions:
- Fork this project to your github account.
- Choose one issue.
- Create a branch with this issue name.
- Make the changes, remembering, the project need pass in the format case(use
mix formattool), test case and the tests must have a good coverage (around 70~80%), usemix coverallsto see the coverage. - Send a push to your branch like
git push origin <your-branch>. - The Github actions will check if your code is fine.
- If is merged the Gigalixir will put running automated.
Note: the merge is checked by admins
To start your Phoenix server:
Enviroment Variables:
export CLOAK_KEY="your-encryption-key"This key can be generated using iex, just open the iex in terminal:
iex -S mixInside iex we just need create the key:
32 |> :crypto.strong_rand_bytes() |> Base.encode64()This command will respond a good key to encrypt our user sensitive data.
"xvbaGxqlwX4+sUg3qO+u/v62rShncj8BVaMmB7VEE3o="Now can make the default Phoenix configuration:
- Install dependencies with
mix deps.get. - Create and migrate your database with
mix ecto.setup. - Install Node.js dependencies with
npm installinside theassetsdirectory. - Start Phoenix endpoint with
mix phx.server.
Remember need a instance of Postgres running and if have a different credentials, need configure in config/dev.exs
Now you can visit localhost:4000 from your browser.
{ "cpf": "12345678935", //11 digits cpf ID "password": "12345678912", //password min 8 digits "country": "Brasil", //Country name "city": "São Paulo", //City name "birth_date": "1990-01-01", //Birth Date of user "gender": null, //Gender is a optional param "referral_code": null, //Can set a code of another user here. "state": "São Paulo", //State/Province name "name": "User Name", //Full name of user "email": "[email protected]" // Email of user }