code4romania / monitorizare-vot-votanti-api

API pentru monitorizarea incidentelor din cadrul alegerilor parlamentare din 2016.

Monitorizare Vot - Rest API

See the project live

Monitorizare Vot is a mobile app for monitoring elections by authorized observers. They can use the app in order to offer a real-time snapshot on what is going on at polling stations and they can report on any noticeable irregularities.

The NGO-s with authorized observers for monitoring elections have real time access to the data the observers are transmitting therefore they can report on how voting is evolving and they can quickly signal to the authorities where issues need to be solved.

Moreover, where it is allowed, observers can also photograph and film specific situations and send the images to the NGO they belong to.

The app also has a web version, available for every citizen who wants to report on election irregularities. Monitorizare Vot was launched in 2016 and it has been used for the Romanian parliamentary elections so far, but it is available for further use, regardless of the type of elections or voting process.

Contributing | Built with | Repos and projects | Deployment | Feedback | License | About Code4Ro

Contributing

This project is built by amazing volunteers and you can be one of them! Here's a list of ways in which you can contribute to this project.

Built With

Uses Laravel 5.2

Main packages:

• JWT-Auth - tymondesigns/jwt-auth
• Dingo API - dingo/api
• Laravel-CORS barryvdh/laravel-cors

Requirements

• PHP 7+ (with mbstring, openSSL extensions);
• Apache or Nginx (mod_rewrite required);
• MySQL;

Repos and projects

Related projects:

• client app - https://github.com/code4romania/monitorizare-vot-votanti-client/
• admin app - https://github.com/code4romania/monitorizare-vot-votanti-admin

Other MV related repos:

• https://github.com/code4romania/monitorizare-vot-admin
• https://github.com/code4romania/monitorizare-vot-ong
• https://github.com/code4romania/monitorizare-vot
• https://github.com/code4romania/monitorizare-vot-android
• https://github.com/code4romania/monitorizare-vot-ios
• https://github.com/code4romania/monitorizare-vot-docs

Deployment

Services

In /tools/docker you can find a docker compose file that starts a php server with apache, a mysql server and a phpmyadmin instance. You will need to have docker and docker-compose(https://docs.docker.com/compose/) installed.

To start the services, go to the tools/docker folder and run:

docker-compose up -d

Project setup

• Install prerequisites

composer install

• Configurations

Initial .env setup

cp .env.docker .env

Add new local keys

php artisan key:generate //Not sure if really neccesary
php artisan jwt:generate

Run DB scrips

php artisan migrate --seed

• Run the local server with

php artisan serve

• Test your storage folders structure

  Sometimes these folders need to be created manually if the user doesn't have the rights to do so:

  • /storage/framework/cache
  • /storage/framework/sessions
  • /storage/framework/views
  • /storage/logs

Access http://localhost:8000 or http://localhost:8000/api/check in the browser to test the project. For documentation you can access http://localhost:8000/api/documentation

• (Optional) Swagger

To generate the swagger files

php artisan l5-swagger:publish
php artisan l5-swagger:generate

Once the files are generated you can access the swagger documentation at: http://localhost:8000/api/documentation

Testing it works

Once everything is built and started you can access the webservice at http://localhost:3200 and the phpmyadmin at http://localhost:3201 . If you are running Linux then you can use the direct IPs as well ( this does not work for Mac or Windows ).

To list the container do:

docker ps

The containers can be accessed by:

docker exec -it <container_name> bash

You can run composer and php commands from inside the container.

To add special configs to the PHP ini inside the container you can modify the config file.

Project structure

• Controllers in /app/Api/V1/Controllers
• Routing in /app/Http/api_routes.php
• See Laravel and Dingo API documentation for more.
• Also: https://www.sitepoint.com/how-to-build-an-api-only-jwt-powered-laravel-app/

Main Features

AuthController

• login();
• signup();
• recovery();
• reset();

You will need:

• login: just email and password;
• signup: whatever you like: you can specify it in the config file;
• recovery: just the user email address;
• reset: token, email, password and password confirmation;

IncidentController Endpoint

• GET /api/incidents ( get last 20 incidents )

• GET /api/incidents?limit=100 (Get more incidents)

• _GET /api/incidents?limit=10&page=3+ (limit parameter is optional, will default to 20)

• GET /api/incidents?status[]=Pending (filter by state)

• GET /api/incidents?status[]=Pending&status[]=Rejected (get pending and rejected)

• POST /api/incidents (Create incident)

• PUT /api/incidents/5/approve (Approve incident - ADMIN)

• PUT /api/incidents/5/reject (Reject incident - ADMIN)

• DELETE /api/incidents/5 (Delete incident - ADMIN)

A Separate File for Routes

You can specify your routes in the api_routes.php file, that will be automatically loaded. In this file you will find many examples of routes.

Secrets Generation

Every time you create a new project starting from this repository, the php artisan jwt:generate command will be executed.

Configuration

As I already told before, this boilerplate is based on dingo/api and tymondesigns/jwt-auth packages. So, you can find many informations about configuration here and here.

However, there are some extra options that I placed in a config/boilerplate.php file.

• signup_fields: you can use this option to specify what fields you want to use to create your user;
• signup_fields_rules: you can use this option to specify the rules you want to use for the validator instance in the signup method;
• signup_token_release: if "true", an access token will be released from the signup endpoint if everything goes well. Otherwise, you will just get a 201 Created response;
• reset_token_release: if "true", an access token will be released from the signup endpoint if everything goes well. Otherwise, you will just get a 200 response;
• recovery_email_subject: here you can specify the subject for your recovery data email;

Creating Endpoints

You can create endpoints in the same way you could to with using the single dingo/api package. You can read its documentation for details.

After all, that's just a boilerplate! :)

Cross Origin Resource Sharing

If you want to enable CORS for a specific route or routes group, you just have to use the cors middleware on them.

Thanks to the barryvdh/laravel-cors package, you can handle CORS easily. Just check the docs at this page for more info.

Feedback

• Request a new feature on GitHub.
• Vote for popular feature requests.
• File a bug in GitHub Issues.
• Email us with other feedback [email protected]

License

This project is licensed under the MPL 2.0 License - see the LICENSE file for details

About Code4Ro

Started in 2016, Code for Romania is a civic tech NGO, official member of the Code for All network. We have a community of over 500 volunteers (developers, ux/ui, communications, data scientists, graphic designers, devops, it security and more) who work pro-bono for developing digital solutions to solve social problems. #techforsocialgood. If you want to learn more details about our projects visit our site or if you want to talk to one of our staff members, please e-mail us at [email protected].

Last, but not least, we rely on donations to ensure the infrastructure, logistics and management of our community that is widely spread across 11 timezones, coding for social change to make Romania and the world a better place. If you want to support us, you can do it here.

monitorizare-vot-votanti-api's Issues

Create endpoint for adding new incidents

/POST /api/incidents

return validation errors or HTTP 201 Created Response.

Create endpoint for deleting an incident

DELETE /api/incidents/{incidentId}

Should return 404 if not found and 200 OK for delete

[Infrastructure] Dockerize solution

Run the API in a Docker container.

Modify add incidents endpoint to accept an image as part of the request

The endpoint at /v1/incidents, when invoked with a POST method, should accept an image as well as part of the request.
Please check the current state of the Incident Controller.
Please check UI issue here: code4romania/monitorizare-vot-votanti-client#65

Create an endpoint to return a list of counties

GET /api/counties => lista judete

Automatic deployment to AWS for develop and master branches

We will have 2 environments:

1. development environment in AWS, using Docker
   Any merge in develop branch deploys the backend services to a host in AWS
2. production environment in AWS, using Docker (but without phpmyadmin)
   Any merge in master branch will deploy the backend service to a host in AWS

Add Swagger-UI for documenting the API

document API using swagger

Pagination doesn't work properly for pending incidents

Related to #8

First two pending incidents pages for /incidents (page 0 and page 1) return the exact same result.

https://portal-votanti-uat.azurewebsites.net/api/incidents?limit=20&page=1&status=Pending
https://portal-votanti-uat.azurewebsites.net/api/incidents?limit=20&page=0&status=Pending

story - ca un superuser sau un user al platformei de admin vreau sa am un rol

superuser:

• Create/Read/Update/Delete pe orice sesizare

user:

• Read/Update pe orice sesizare

Actiunea de update se refera la update-ul statusului unei sesizari, orice alta informatie ramane user generated content. Statusuri valide: submitted, approved, rejected

Create pagination for /incidents endpoint

Write a test suite for the incidents endpoints

This would help with general confidence in the app functionality.

Add pages controller to perform operations on pages entity

Related to https://github.com/code4romania/monitorizare-vot-votanti-admin/issues/16
Related to https://github.com/code4romania/monitorizare-vot-votanti-admin/issues/17
Related to https://github.com/code4romania/monitorizare-vot-votanti-admin/issues/18

Add a controller in order to perform the following operations on Pages entity:

• Add new page
• View all pages
• Edit page
• Approve/Reject pages
• Delete pages

Create a new endpoint to return stats about the incidents

total incidents
incidents by county
...

Enhance PrecinctController with endpoint to add precincts

Currently the precincts are created and inserted manually by running a script to import this information in the database.

The PrecinctController needs to be enhanced to receive requests for insert from the frontend.
The PrecinctController should be able to receive a csv/xlsx file, similar to the one in resources/files/precincts and update the information in the database.

Add form controller to access form entity and perform operations on form

Linked to https://github.com/code4romania/monitorizare-vot-votanti-admin/issues/14
Linked to #19
Linked to https://github.com/code4romania/monitorizare-vot-votanti-admin/issues/15

Add form controller in order to perform operations on form entities:

• Add new form
• Display all forms
• Activate/Deactivate form
• Edit form
• Delete form

story - ca un dezvoltator al platformelor de admin/client as vrea un model al sesizarii

Acestui model de date as vrea sa-i pot face operatiuni CRUD prin expunerea la API.

{
    "name": "Ionescu Popescu",
    "county": "Teleorman",
    "city": "Dragnesti",
    "station_id": 123,
    "issue_type": 5,
    "description": "Star stuff harvesting star light Flatland Rig Veda! Cosmos citizens of distant epochs hundreds of thousands. Shores of the cosmic ocean Flatland citizens of distant epochs, cosmos shores of the cosmic ocean Flatland, a billion trillion inconspicuous motes of rock and gas, birth.",
    "image": "sesizare.jpg",
    "e-mail": "[email protected]",
    "phone": "[phone]",
    "status": 0
}

Laravel is outdated

This API uses a version of Laravel that is very old (21/12/2015). It should be upgraded to at least 5.5 (LTS) in order to receive security upgrades.

I can't say for sure how hard the upgrade will be but I don't expect any major issues. The code could also be updated to use some of the modern Laravel features such as gates to make it more readable.

Endpoint to fetch reports overview

one endpoint to include all the reporting data

Add form model to project

Linked to Client issue https://github.com/code4romania/monitorizare-vot-votanti-admin/issues/14

A new entity needs to be added to the project, name of the entity is form, this entity will hold forms displayed in the app.
Fields:
titlu -> string
autor -> user reference
data -> date field
status -> string
fields -> list of fields that need to be displayed as part of the form

Add pages model to project

Linked to https://github.com/code4romania/monitorizare-vot-votanti-admin/issues/16

A new model needs to be added to the project: Pages
The model will contain the information for displaying voting rules and other pages available on the public platform.
Fields:
titlu -> string
autor -> user reference
date -> date field
status -> string
description -> text that is displayed on page website in frontend
*EDIT: after reviewing the requirements for the public platform, the data model should be enhanced with the following fields
logo -> image for the logo of the page, displayed in the frontend
child_pages -> list of ids for child pages

Return number of unread/accepted/rejected messages

The backend should return the number of messages that are unread/accepted/rejected.
The information needs to be used on the Messages page on the frontend.

story - ca un dezvoltator al platformelor de admin/client as vrea sa am o separare a dezvoltarii de mediul de productie

local - localhost:1234
pre-prod - pre-prod.monitorizarevot.ro
prod - monitorizarevot.ro

Remove secrets from repo

One example is the admin password in the users table seeder. Instead of having a hardcoded password, it should be generated randomly when the seeder is run and the password can be show in the console.

Edit the type of incidents available in the application

Enhance the IncidentType controller to accept a POST method for adding incident types from the frontend.
The datamodel of the request should be the same as the datamodel persisted:

• Label
• Code
• Name
  Please check IncidentTypeController.php and the api_routes.php to create the new route.

Enhance the IncidentType controller to accept a POST method for adding a list of incident types from the front end. The datamodel of the objects sent from frontend is the same as above:

• Label
• Code
• Name
  Please check IncidentTypeController.php and the api_routes.php to create the new route.

story - ca un dezvoltator al platformelor de admin/client as vrea sa am date preinstalate in aplicatie

Seed Incidents

The seeder IncidentsTableSeeder is commented out in DatabaseSeeder and this is affecting my local testing.

The IncidentTypesTableSeeder excludes IDs 6 and 10. I'm guessing this broke the seed at some point and this was just left as is.

My proposed fix is to update IncidentsTableSeeder to exclude those IDs.

Endpoint to fetch precincts by city

Create endpoint for approve/reject incident

PUT /api/incidents/{incidentId}/approve
PUT /api/incidents/{incidentId}/reject

Should return 404 Not Found if incident object is not found.

Endpoint to retrive international precincts

Restructure/build another forms endpoint

I suggest we either restructure this endpoint, or create a new one that has a better data. We need this in order to have the form description along with the ID, to be displayed in the UI.

Right now, the /formular/versiune endpoint returns this:

{
    "versiune": {
        "A": 3,
        "B": 3,
        "C": 2
    }
}

I would suggest that the returned object be an array of objects, instead of a hashmap, so we can store more properties.

It would make sense building a different one, since its purpose would be a bit different.

GET /formulare

{
    "formulare": [
        {
            "id": "A",
            "descriere": "Primul formular",
            "ver": 3
        },
        {
            "id": "B",
            "descriere": "Al doilea",
            "ver": 2
        },
        ...
    ]
}

This way we can show the description in the UI (before today it was hard coded in the app):

"Label_FormA" = "Saturday Form";
"Label_FormB" = "Sunday Form";
"Label_FormC" = "Counting Form";