apiary.apib

FORMAT: 1A
HOST: https://blackpolitico-api-heroku.herokuapp.com

# Politico API

**POLITICO API** Is a pure Flask REST API app that serves endpoints for political parties,government offices,
petitioning,voting and user login and sign up to be consumed by front end frameworks.

# Group Offices

## Offices Collection [/api/v2/offices]

### Gets All Offices [GET]

A User with an authentication token can view all offices available.

+ Response 200 (application/json)

            {
                "data":[
                         {
                             "id":1,
                             "name":"office_name",
                             "type":"office_type"                 
                         },
                         {
                             "id":2,
                             "name":"office_name",
                             "type":"office_type"                 
                         },
                         {
                             "id":3,
                             "name":"office_name",
                             "type":"office_type"                 
                         }
                       ],
                "status" : 200       
            }
            
### Create a New Office [POST]

An admin user with an admin authentication token can create an office. 

+ Request (application/json)
   
   + Headers
    
            Authorization: Bearer Token
            Location: /api/v2/offices
  
   + Body
    
            {
                "type": "office_type",
                "name":"office_name"
            }

+ Response 201 (application/json)

            {
              "data":[
                {
                   "name":"office_name"
                }
              ],
              "status":201
            }
            
+ Request (application/json)
    
       
    + Headers
    
            Authorization: Bearer Token
            Location: /api/v2/offices

    + Body

            {
                "type": "ofte",
                "name":"ofe"
            }
            
+ Response 400 (application/json)
    
            {
              "status":400,
              "error":"Check Input Values"
            }


## Specific Office Collection [/api/v2/offices/{office_id}]

+ Parameters

    + office_id (number) - ID of office to which operations will be done on
    

### Edit An Office [PATCH]

A User with an admin authentication token can edit an office.

+ Request (application/json)

   + Headers
    
            Authorization: Bearer Token
     
   + Body   
   
            {
                "name":"office_name"
            } 

+ Response 200 (application/json)

            {
             "message":"Updated Successfully",
             "status":200
            }

### Get an Office [GET]            
            

An user with an authentication token can view an office. 

+ Request (application/json)
   
   + Headers
    
            Authorization: Bearer Token
  
+ Response 201 (application/json)

            {
              "id" :1
              "office_type":"Type Of Office"
              "office_name":"Name Of Office"
            }


        
### Delete an Office [DELETE]            
            

An admin user with an admin authentication token can delete an office. 

+ Request (application/json)
   
   + Headers
    
            Authorization: Bearer Token
  
+ Response 201 (application/json)

            {
              "message":"{office_name} Deleted"
              "status":200
            }
            
# Group Parties

## Parties Collection [/api/v2/parties]

### Gets All Parties [GET]

A User with authentication token can view all parties.

+ Request

    + Headers

            Authorization: Bearer Token
            
+ Response 200 (application/json)

            {
                "data":[
                         {
                             "id":1,
                             "name":"office_name",
                             "hqAddress":"logo_url",
                             "logoUrl":"logo_url"
                         },
                         {
                             "id":2,
                             "name":"office_name",
                             "hqAddress":"logo_url",
                             "logoUrl":"logo_url"
                         },
                         {
                             "id":3,
                             "name":"office_name",
                             "hqAddress":"logo_url",
                             "logoUrl":"logo_url"
                         },
                       ],
                "status" : 200       
            }

### Create a New Party [POST]

An admin user with admin authentication token can create a party.

+ Request (application/json)

    + Headers

            Authorization: Bearer Token

    + Body

            {
                "name": "office_type",
                "hqAddress":"office_name",
                "logoUrl":"logo_url"
            }

+ Response 201 (application/json)

    + Body

            {
              "data":[
                {
                  "name":"party_name"
                }
              ],
              "status":201
            }

## Specific Party Collection [/api/v2/parties/{party_id}]

+ Parameters

    + party_id (number) - ID of party to which operations will be done on
    

### Edit A Party [PATCH]

A User with an admin authentication token can edit a parties name.

+ Request (application/json)

   + Headers
    
            Authorization: Bearer Token
     
   + Body   
   
            {
                "name":"party_name"
            } 

+ Response 200 (application/json)

            {
             "message":"Updated Successfully",
             "status":200
            }

### Get an Party [GET]            
            

An user with an authentication token can view a party. 

+ Request (application/json)
   
   + Headers
    
            Authorization: Bearer Token
  
+ Response 201 (application/json)

            {
              "id" :1,
              "name":"Name Of Party",
              "hqAddress":"Address Of Party",
              "logoUrl":"Party Logo Url"
            }


        
### Delete a Party [DELETE]            
            

An admin user with an admin authentication token can delete a party. 

+ Request (application/json)
   
   + Headers
    
            Authorization: Bearer Token
  
+ Response 201 (application/json)

            {
              "message":"{party_name} Deleted"
              "status":200
            }


            
# Group Users

## User Sign Up [/api/v2/auth/signup]

### Sign Up [POST]

A new user can Sign Up on the platform

+ Request (application/json)

   + Body
              
            {
                "firstname": "Davied",
                "lastname": "Odari",
                "othername": "Kiribwa",
                "email": "odari@amail.com",
                "phoneNumber": "0717455945",
                "passportUrl": "www.googledrive.com/pics?v=jejfek",
                "password": "1wwjdje3qr",
                "isAdmin": 0 
            }     
            
        
                     
        
+ Response 201 (application/json)

            {
                   "status": 201,
                   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NTA4MTY0MjYsIm5iZiI6MTU1MDgxNjQyNiwianRpIjoiODBhZDU0ZTEtNjVlYS00NDczLWI3NjItNDI2ODIwZjY1ZWI3IiwiZXhwIjoxNTUwODE3MzI2LCJpZGVudGl0eSI6MSwiZnJlc2giOmZhbHNlLCJ0eXBlIjoiYWNjZXNzIn0.Bz7tvf81A4ks660nOWZOyRY9J0TsFG05jDVJ13mBYL8"
            }
            
+ Request
         
   + Body 
   
   
            {
                "firstname": "Davied",
                "lastname": "Odari",
                "othername": "Kiribwa",
                "email": "odari@amail.com",
                "phoneNumber": "0717455945",
                "passportUrl": "www.googledrive.com/pics?v=jejfek",
                "password": "1wwjdje3qr",
                "isAdmin": 0 
            }
            
+ Response 409 (application/json)

   + Body
            
            {
               "status": 409,
               "error": "User Already Exists"
            }  


## User Login [/api/v2/auth/login]

### Login [POST]

An existing user can login to the system.

+ Request (application/json)

    + Headers
       
            Authorization: Bearer Token

    + Body

            {
                "email": "odari@amail.com",
                "password": "1wwjdje3qr"
            }

+ Response 201 (application/json)

    + Body

            {
              "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NTA4MTU2OTcsIm5iZiI6MTU1MDgxNTY5NywianRpIjoiOTljNjc4MDQtOTUxMy00OGI5LTgxYzEtNGU2YWMyNjQ0M2MxIiwiZXhwIjoxNTUwODE2NTk3LCJpZGVudGl0eSI6MSwiZnJlc2giOmZhbHNlLCJ0eXBlIjoiYWNjZXNzIn0.hZPrc6-D6mD8a_DPRquBpfLyvUn3ZTjRfFErE2DWin0",
              "status":201
             }

# Group Candidates            
            
## Candidate Collection [/office/{office_id}/register]

+ Parameters

    + office_id (number) - ID of office to which candidate will be registered
    

### Register a Candidate [POST]

A signed up user can be registered as a candidate

+ Request (application/json)

    + Headers
       
            Authorization: Bearer Token

    + Body

            {
                "party": 1,
                "candidate": 2
            }

+ Response 201 (application/json)

    + Body

            {
              "data":[
                {
                 "office": "office_name",
                 "user": "user_name"
                }
              ],
              "status":201
             }

### View Candidates [GET]

A user who is logged in can view candidates for a specific office

+ Request (application/json)

    + Headers
       
            Authorization: Bearer Token


+ Response 201 (application/json)

    + Body

            {
              "data":[
                {
                
                 "office": "office_name",
                 "user": "user_name"
                 
                },
                { 
                
                 "office": "office_name",
                 "user": "user_name"
                 
                },
                { 
                
                 "office": "office_name",
                 "user": "user_name"
                 
                }
              ],
              "status":201
             }

# Group Votes

## Vote Collection [/votes/]

### Vote For a Registered Candidate [POST]

A signed up user can vote for a registered candidate

+ Request (application/json)

    + Headers
       
            Authorization: Bearer Token

    + Body

            {
                "voter": 1,
                "office":1,
                "candidate": 2
            }

+ Response 201 (application/json)

    + Body

            {
              "data":[
                {
                     "office":1
                     "candidate": 2,
                     "voter": 1
                }
              ],
              "status":201
             }

# Group Results

## Results Collection [/office/{office_id}/results]

+ Parameters

    + office_id (number) - ID of office to which candidates are registered

   
   
### View Results for Candidates of a specific office [GET]

A signed up user can view results on request

+ Request (application/json)

    + Headers
       
            Authorization: Bearer Token


+ Response 201 (application/json)

    + Body

            {
              "data":[
                {
                 "office": 1,
                 "candidate": 4,
                 "results":340
                }
              ],
              "status":200
             }