apiary.apib

FORMAT: 1A
HOST: http://openelect.org/api/v1/

# OpenElect

A platform for secure, verifiable elections built in node.js.

# OpenElect API Root [/]

This resource does not have any attributes. Instead it offers the initial
API affordances in the form of the links in the JSON body.

## Retrieve the Entry Point [GET]

+ Response 200 (application/json)

        {
            "elections_url": "/api/v1/elections",
            "create_election": "/api/v1/elections/create"
            "update_electoin": "/api/v1/elections/{id}"
        }

## Group Elections

Resources related to Elections in the API.

## Election [/elections]

Elections are the top-level organizational unit for OpenElect content. Elections contain polls, which contain questions. 

+ question
+ published_at - An ISO8601 date when the question was published.
+ url
+ choices - An array of Choice objects.

+ Parameters
    + election_id (required, number, `1`) ... ID of the Election in form of an integer

### List all Elections [GET]

+ Response 200 (application/json)

                [
                    {
                    "id": 2,
                    "owner_id": 1,
                    "name": "2016 Federal Electioons",
                    "description": "Federal elections for United States Presidency and Congress",
                    "start": "2016-11-08T08:00:00.000Z",
                    "end": "2016-11-10T08:00:00.000Z",
                    "timed": true,
                    "accepting_votes": null,
                    "locked": null,
                    "privacy_strategy": "secret",
                    "url_handle": null,
                    "randomize_answer_order": true,
                    "two_factor_auth": true,
                    "force_two_factor_auth": false,
                    "results": null,
                    "created_at": "2015-04-10T23:18:16.016Z",
                    "updated_at": "2015-04-10T23:18:16.016Z",
                    "poll": [ ]
                    }
                ]

## Choice [/questions/{question_id}/choices/{choice_id}]

+ Parameters
    + question_id (required, number, `1`) ... ID of the Question in form of an integer
    + choice_id (required, number, `1`) ... ID of the Choice in form of an integer

### Vote on a Choice [POST]

This action allows you to vote on a question's choice.

+ Response 201

    + Headers

            Location: /questions/1

## Questions Collection [/questions{?page}]

+ Parameters
    + page (optional, number, `1`) ... The page of questions to return

### List All Questions [GET]

+ Response 200 (application/json)

    + Headers

            Link: </questions?page=2>; rel="next"

    + Body

            [
                {
                    "question": "Favourite programming language?",
                    "published_at": "2014-11-11T08:40:51.620Z",
                    "url": "/questions/1",
                    "choices": [
                        {
                            "choice": "Swift",
                            "url": "/questions/1/choices/1",
                            "votes": 2048
                        }, {
                            "choice": "Python",
                            "url": "/questions/1/choices/2",
                            "votes": 1024
                        }, {
                            "choice": "Objective-C",
                            "url": "/questions/1/choices/3",
                            "votes": 512
                        }, {
                            "choice": "Ruby",
                            "url": "/questions/1/choices/4",
                            "votes": 256
                        }
                    ]
                }
            ]

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON
object containing a question and a collection of answers in the
form of choices.

+ question (string) - The question
+ choices (array[string]) - A collection of choices.

+ Request (application/json)

            {
                "question": "Favourite programming language?",
                "choices": [
                    "Swift",
                    "Python",
                    "Objective-C",
                    "Ruby"
                ]
            }

+ Response 201 (application/json)

    + Headers

            Location: /questions/2

    + Body

                {
                    "question": "Favourite programming language?",
                    "published_at": "2014-11-11T08:40:51.620Z",
                    "url": "/questions/2",
                    "choices": [
                        {
                            "choice": "Swift",
                            "url": "/questions/2/choices/1",
                            "votes": 0
                        }, {
                            "choice": "Python",
                            "url": "/questions/2/choices/2",
                            "votes": 0
                        }, {
                            "choice": "Objective-C",
                            "url": "/questions/2/choices/3",
                            "votes": 0
                        }, {
                            "choice": "Ruby",
                            "url": "/questions/2/choices/4",
                            "votes": 0
                        }
                    ]
                }