Skip to content

Polls Hypermedia API.md

Latest commit

 

History

History
623 lines (569 loc) · 19.8 KB

Polls Hypermedia API.md

File metadata and controls

623 lines (569 loc) · 19.8 KB

FORMAT: 1A HOST: http://polls.apiblueprint.org/

Polls

Polls is a simple API allowing consumers to view polls and vote in them. You can view this documentation over at Apiary.

Polls API Root [/]

This resource does not have any attributes. Instead it offers the initial API affordances.

Retrieve the Entry Point [GET]

  • Response 200 (application/vnd.siren+json)

      {
      "links": [
          {
              "rel": [ "questions" ],
              "href": "/questions"
          }
      ]
  }

  • Response 200 (application/hal+json)

      {
      "_links": {
          "questions": { "href": "/questions" }
      }
  }

Questions Collection [/questions{?page}]

  • Parameters
    • page: 1 (optional, number) - The page of questions to return

List All Questions [GET]

  • Relation: questions

  • Response 200 (application/vnd.siren+json)

      {
      "actions": [
          {
              "name": "add",
              "href": "/questions",
              "method": "POST",
              "type": "application/json",
              "fields": [
                  {
                      "name": "question"
                  }, {
                      "name": "choices"
                  }
              ]
          }
      ],
      "links": [
          {
            "rel": [ "next" ],
            "href": "/questions?page=2"
          },
          {
            "rel": [ "self" ],
            "href": "/questions"
          }
      ],
      "entities": [
          {
              "actions": [
                  {
                      "name": "delete",
                      "href": "/questions/1",
                      "method": "DELETE"
                  }
              ],
              "rel": [ "question" ],
              "properties": {
                  "published_at": "2014-11-11T08:40:51.620Z",
                  "question": "Favourite programming language?"
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1"
                  }
              ],
              "entities": [
                  {
                      "actions": [
                          {
                              "name": "vote",
                              "href": "/questions/1/choices/1",
                              "method": "POST"
                          }
                      ],
                      "rel": [ "choice" ],
                      "properties": {
                          "choice": "Swift",
                          "votes": 2048
                      },
                      "links": [
                          {
                              "rel": [ "self" ],
                              "href": "/questions/1/choices/1"
                          }
                      ]
                  }, {
                      "actions": [
                          {
                              "name": "vote",
                              "href": "/questions/1/choices/2",
                              "method": "POST"
                          }
                      ],
                      "rel": [ "choice" ],
                      "properties": {
                          "choice": "Python",
                          "votes": 1024
                      },
                      "links": [
                          {
                              "rel": [ "self" ],
                              "href": "/questions/1/choices/2"
                          }
                      ]
                  }, {
                      "actions": [
                          {
                              "name": "vote",
                              "href": "/questions/1/choices/3",
                              "method": "POST"
                          }
                      ],
                      "rel": [ "choice" ],
                      "properties": {
                          "choice": "Objective-C",
                          "votes": 512
                      },
                      "links": [
                          {
                              "rel": [ "self" ],
                              "href": "/questions/1/choices/3"
                          }
                      ]
                  }, {
                      "actions": [
                          {
                              "name": "vote",
                              "href": "/questions/1/choices/4",
                              "method": "POST"
                          }
                      ],
                      "rel": [ "choice" ],
                      "properties": {
                          "choice": "Ruby",
                          "votes": 256
                      },
                      "links": [
                          {
                              "rel": [ "self" ],
                              "href": "/questions/1/choices/4"
                          }
                      ]
                  }
              ]
          }
      ]
  }

  • Response 200 (application/hal+json)

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

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.

  • Relation: create

  • Request (application/json)

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

  • Response 201 (application/vnd.siren+json)

      {
      "actions": [
          {
              "name": "delete",
              "href": "/questions/1",
              "method": "DELETE"
          }
      ],
      "properties": {
          "published_at": "2014-11-11T08:40:51.620Z",
          "question": "Favourite programming language?"
      },
      "links": [
          {
              "rel": [ "self" ],
              "href": "/questions/1"
          }
      ],
      "entities": [
          {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/1",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Swift",
                  "votes": 2048
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/1"
                  }
              ]
          }, {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/2",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Python",
                  "votes": 1024
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/2"
                  }
              ]
          }, {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/3",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Objective-C",
                  "votes": 512
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/3"
                  }
              ]
          }, {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/4",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Ruby",
                  "votes": 256
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/4"
                  }
              ]
          }
      ]
  }

  • Response 201 (application/hal+json)

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

Group Question

Resources related to questions in the API.

Question [/questions/{question_id}]

A Question object has the following attributes:

  • question

  • published_at - An ISO8601 date when the question was published.

  • url

  • choices - An array of Choice objects.

  • Parameters

    • question_id: 1 (required, number) - ID of the Question in form of an integer

View a Questions Detail [GET]

  • Relation: question

  • Response 200 (application/vnd.siren+json)

      {
      "actions": [
          {
              "name": "delete",
              "href": "/questions/1",
              "method": "DELETE"
          }
      ],
      "properties": {
          "published_at": "2014-11-11T08:40:51.620Z",
          "question": "Favourite programming language?"
      },
      "links": [
          {
              "rel": [ "self" ],
              "href": "/questions/1"
          }
      ],
      "entities": [
          {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/1",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Swift",
                  "votes": 2048
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/1"
                  }
              ]
          }, {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/2",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Python",
                  "votes": 1024
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/2"
                  }
              ]
          }, {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/3",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Objective-C",
                  "votes": 512
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/3"
                  }
              ]
          }, {
              "actions": [
                  {
                      "name": "vote",
                      "href": "/questions/1/choices/4",
                      "method": "POST"
                  }
              ],
              "rel": [ "choices" ],
              "properties": {
                  "choice": "Ruby",
                  "votes": 256
              },
              "links": [
                  {
                      "rel": [ "self" ],
                      "href": "/questions/1/choices/4"
                  }
              ]
          }
      ]
  }

  • Response 200 (application/hal+json)

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

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

  • Parameters
    • question_id: 1 (required, number) - ID of the Question in form of an integer
    • choice_id: 1 (required, number) - ID of the Choice in form of an integer

View a Choice Detail [GET]

  • Relation: choice

  • Response 200 (application/vnd.siren+json)

      {
      "actions": [
          {
              "name": "vote",
              "href": "/questions/1/choices/1",
              "method": "POST"
          }
      ],
      "rel": [ "choice" ],
      "properties": {
          "choice": "Swift",
          "votes": 2048
      },
      "links": [
          {
              "rel": [ "self" ],
              "href": "/questions/1/choices/1"
          }
      ]
  }

  • Response 200 (application/hal+json)

      {
      "_links": {
          "self": { "href": "/questions/1/choices/1" }
      },
      "choice": "Swift",
      "votes": 2048
  }

Vote on a Choice [POST]

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

  • Relation: vote

  • Response 201 (application/vnd.siren+json)

      {
      "actions": [
          {
              "name": "vote",
              "href": "/questions/1/choices/1",
              "method": "POST"
          }
      ],
      "rel": [ "choice" ],
      "properties": {
          "choice": "Swift",
          "votes": 2049
      },
      "links": [
          {
              "rel": [ "self" ],
              "href": "/questions/1/choices/1"
          }
      ]
  }

  • Response 201 (application/hal+json)

      {
      "_links": {
          "self": "/questions/1/choices/1"
      },
      "choice": "Swift",
      "votes": 2049
  }