Toastmasters API

Welcome to Toastmasters API documentation.

Setup

• brew install postgres (>= 9.4)
• rbenv install 2.2.2; rbenv global 2.2.2
• gem install bundler foreman
• bundle install
• createdb toastmasters; bundle exec rake db:migrate
• foreman start

Table of contents

• Introduction
• Meetings
• Members
• Guests
• Participations
• Speeches

Introduction

The format used for requests and responses is JSON API, with the media type application/vnd.api+json. Every request requires HTTP basic authentication:

GET /meetings HTTP/1.1
Authorization: Basic dG9hc3RtYXN0ZXJzOnNlY3JldA==

Errors that happen in the request will be returned, and sometimes the "meta" key will return error data:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errors": [
    {
      "id": "unauthorized",
      "title": "The request requires authentication",
      "status": 401,
      "meta": {}
    }
  ]
}

Meetings

Attribute	Type
id	string
date	date
note	string

When singular meetings are returned, a list of participations will also be returned.

Listing meetings

GET /meetings HTTP/1.1

GET /meetings/43 HTTP/1.1

Creating meetings

POST /meetings HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "meetings",
    "attributes": {
      "date": "2015-01-01",
    }
  }
}

Updating meetings

PATCH /meetings/43 HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "meetings",
    "id": "43",
    "attributes": {
      "note": "A note about the meeting",
    }
  }
}

Deleting meetings

DELETE /meetings/43 HTTP/1.1

Members

Attribute	Type
id	string
first_name	string
last_name	string
email	string
active	boolean

Listing members

GET /members HTTP/1.1

GET /members/43 HTTP/1.1

Creating members

POST /members HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "members",
    "attributes": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "[email protected]",
    }
  }
}

Updating members

PATCH /members/43 HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "members",
    "id": "43",
    "attributes": {
      "active": false,
    }
  }
}

Deleting members

DELETE /members/43 HTTP/1.1

Listing speeches

GET /members/43/speeches HTTP/1.1

This will list all of member's speeches in chronological order.

Guests

Attribute	Type
id	string
first_name	string
last_name	string
email	string

Listing guests

GET /guests HTTP/1.1

GET /guests/43 HTTP/1.1

Creating guests

POST /guests HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "guests",
    "attributes": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "[email protected]",
    }
  }
}

If a guest already exists with given attributes, returns it rather than creating a new one.

Updating guests

PATCH /guests/43 HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "guests",
    "id": "43",
    "attributes": {
      "first_name": "Edward",
    }
  }
}

Deleting guests

DELETE /guests/43 HTTP/1.1

Participations

Attribute	Type
id	string
role	string
role_data	json

Valid roles are:

role	role_data
Toastmaster
General Evaluator
Speaker	{"speech_id": "123"}
Evaluator	{"speaker_id": "22"}
Table TopicsMaster
Timer
Grammarian
Ah-Counter

Participations have associations meeting, member and guest.

Listing participations

GET /meetings/12/participations HTTP/1.1

Creating participations

POST /meetings/12/participations HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "participations",
    "attributes": {
      "role": "Evaluator",
      "role_data": {}
    },
    "relationships": {
      "member": {
        "data": {"type": "members", "id": "25"}
      }
    }
  }
}

We can create either a "member" or a "guest" participation by putting the appropriate name in "relationships".

{"relationships": {"member": {"data": {"type": "members", "id": "25"}}}}
{"relationships": {"guest": {"data": {"type": "guests", "id": "42"}}}}

Updating participations

PATCH /meetings/12/participations/43 HTTP/1.1
Content-Type: application/json

{
  "data": {
    "type": "participations",
    "id": "43",
    "attributes": {
      "role_data": {"speaker_id": 22},
    }
  }
}

Deleting participations

DELETE /meetings/12/participations/43 HTTP/1.1

Speeches

Attribute	Type
id	string
title	string
number	integer

Listing speeches

GET /speeches HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [{
    "type": "speeches",
    "id": "25",
    "attributes": {
      "title": "How to Say it",
      "number": 4
    },
    "relationships": {
      "manual": {
        "data": {"type": "manuals", "id": "7"}
      }
    }
  }],
  "included": [{
    "type": "manuals",
    "id": "7",
    "attributes": {
      "name": "Competent Communicator"
    }
  }]
}