README.md

API documentation

Koala has an API endpoint for a few applications; radio, zuil, and checkout, but there are many more possibilities. This documentation describes the possible routes and responses divided in; members, groups, activities, participants, and checkout.

Members

Groups

Activities

Activities are used by radio and the zuil and radio also shows commercials of companies. These routes are publically available, however authenticating with the activity-read rights gives you more information about the activities.

Retrieve activities with posters

GET /api/activities HTTP/1.1
Host → koala.svsticky.nl

HTTP/1.1 200 OK
Content-Type → application/json; charset=utf-8

[
  {
    "name": "Bord- en Kaartspellenavond",
    "start_date": "2016-02-08",
    "end_date": null,
    "poster": "https://sticky-posters.s3.amazonaws.com/activities/195/medium/Poster_%281%29.png?1453461841"
  },
  {
    "name": "Git Workshop",
    "start_date": "2016-02-16",
    "end_date": "2016-02-19",
    "poster": "https://sticky-posters.s3.amazonaws.com/activities/196/medium/gitgud-poster.png?1453679092"
  }
]

Participant

Checkout

All checkout endpoints require a secret called token declared in the configuration of .env. A generic response because of this would be a forbidden response meaning that the secret does not correspond with the secret of koala.

HTTP/1.1 403 FORBIDDEN
Content-Type → application/json; charset=utf-8

Below are the endpoints that can be used for checkout.

Retrieve products

GET /api/checkout/products HTTP/1.1
Host → koala.svsticky.nl

+ token          :string (required)

HTTP/1.1 200 OK
Content-Type → application/json; charset=utf-8

[
  {
    "id": 98,
    "name": "7up",
    "category": 1,
    "price": "0.4",
    "image": "https://sticky-posters.s3.amazonaws.com/checkout_products/7?1433681363"
  },
  {
    "id": 100,
    "name": "Coca Cola regular",
    "category": 1,
    "price": "0.53",
    "image": "https://sticky-posters.s3.amazonaws.com/checkout_products/1?1433681225"
  }
]

Information for card

GET /api/checkout/card HTTP/1.1
Host → koala.svsticky.nl

+ token          :string (required)
+ uuid           :string (required) - unique identifier of the OV-card

HTTP/1.1 200 OK
Content-Type → application/json; charset=utf-8

{
  "id": 9,
  "uuid": "EDD411C4",
  "first_name": "Martijn",
  "balance": "4.15"
}

# card with that specific uuid not found
HTTP/1.1 404 NOT FOUND
Content-Type → application/json; charset=utf-8

Create a new card and add to member

POST /api/checkout/card HTTP/1.1
Host → koala.svsticky.nl

+ token          :string (required)
+ student        :string (required) - student id as known by koala
+ uuid           :string (required)
+ description    :string

HTTP/1.1 201 CREATED
Content-Type → application/json; charset=utf-8

{
  "id": 9,
  "uuid": "EDD411C4",
  "first_name": "Martijn",
  "balance": "0.0"
}

# Student could not be found, make sure the student id is correct
HTTP/1.1 404 NOT FOUND
Content-Type → application/json; charset=utf-8

# This uuid is already registered to some student
HTTP/1.1 409 CONFLICT
Content-Type → application/json; charset=utf-8

Create a new transaction

POST /api/checkout/transaction HTTP/1.1
Host → koala.svsticky.nl

+ token          :string (required)
+ uuid           :string (required)
+ items          :array  (required) - array with item ids

HTTP/1.1 201 CREATED
Content-Type → application/json; charset=utf-8

{
  "uuid": "EDD411C4",
  "first_name": "Martijn",
  "balance": "0.9",
  "created_at": "2016-02-06T10:33:50.382+01:00"
}

# Card is not yet activated
HTTP/1.1 401 UNAUTHORIZED
Content-Type → application/json; charset=utf-8

# One of the items in your array is not found or
# there is no card with the specified uuid
HTTP/1.1 404 NOT FOUND
Content-Type → application/json; charset=utf-8

HTTP/1.1 413 REQUEST ENTITY TOO LARGE
Content-Type → application/json; charset=utf-8

{
  "message": "insufficient funds",
  "balance": "2.9",
  "items": [
    1,
    2,
    2
  ],
  "costs": "-4.6"
}

# Not allowed to buy alcohol at the moment
HTTP/1.1 406 NOT ACCEPTABLE
Content-Type → application/json; charset=utf-8

{
  "message": "alcohol allowed at 16:00"
}