d120 · fdamken · Jan 26, 2017 · Jan 24, 2017 · Jan 24, 2017 · Jan 24, 2017
diff --git a/api-documentation/README.md b/api-documentation/README.md
@@ -0,0 +1,34 @@
+# REST API Documentation
+
+The REST API documentation is written in [API Blueprint][2] using [Aglio][1] for rendering the documentation into HTML.
+
+
+## Setup
+
+Setting up [Aglio][1] is pretty easy, you just have to install [NodeJS][3]/[NPM][4] and then run `npm install -g aglio`.
+
+
+## Development
+
+For developing on the API you may start the [Aglio][1] server using `aglio -i api-documentation.md -s` and access the server at `http://localhost:3000`. The page is automatically refreshed when files change.
+
+
+## Compiling before Pushing
+
+Please compile the documentation before pushing your changes using `aglio -i api-documentation.md -o api-documentation.html`.
+
+
+## Documentation
+
+You can find the specification of [API Blueprint][2] here: [Specification][5]
+
+To get the most out of [API Blueprint][2], you have to use this [tool][6].
+
+
+
+[1]: https://github.com/danielgtaylor/aglio
+[2]: https://apiblueprint.org
+[3]: https://nodejs.org
+[4]: https://www.npmjs.com
+[5]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md
+[6]: https://www.google.com
diff --git a/api-documentation/api-documentation.html b/api-documentation/api-documentation.html
diff --git a/api-documentation/api-documentation.md b/api-documentation/api-documentation.md
@@ -0,0 +1,9 @@
+FORMAT: 1A
+HOST: https://www.d120.de/studierende/buchaktion/api
+
+# pyBuchaktion
+
+pyBuchaktion REST API Documentation Version 1.0
+
+<!-- include(datastructures/datastructures.md) -->
+<!-- include(routes/routes.md) -->
diff --git a/api-documentation/datastructures/account.md b/api-documentation/datastructures/account.md
@@ -0,0 +1,7 @@
+## Account
+
+<!-- TODO: To be updated. -->
+
+| Attribute | Type   | Classifier | Description            | Example |
+|-----------|--------|------------|------------------------|---------|
+| id        | number | required   | The ID of the account. | `1987`  |
diff --git a/api-documentation/datastructures/basic.md b/api-documentation/datastructures/basic.md
@@ -0,0 +1,10 @@
+## Basic
+
+### Date
+A date encoded in the format `YYYY-MM-DD`.
+
+### ISBN-13
+An ISBN-13 without the dashes.
+
+### TUCaN-ID
+A course ID of TUCaN (format: `XX-XX-XXXX-XX` where `X` is any alphanumeric character).
diff --git a/api-documentation/datastructures/book.md b/api-documentation/datastructures/book.md
@@ -0,0 +1,10 @@
+## Book
+
+| Attribute | Type                                                                        | Classifier | Description              | Example                    |
+|-----------|-----------------------------------------------------------------------------|------------|--------------------------|----------------------------|
+| id        | number                                                                      | required   | The ID of the book.      | `2444`                     |
+| isbn      | isbn                                                                        | required   | The status of the order. | `9783836218023`            |
+| title     | string                                                                      | required   | The title of the book.   | `Java ist auch eine Insel` |
+| state     | enum[string] { `AC` Accepted, `RJ` Rejected, `PP` Proposed, `OL` Obsolete } |            | The state of the book.   | `AC`                       |
+| author    | string                                                                      | required   | The author of the book.  | `Christian Ullenboom`      |
+| price     | number                                                                      |            | The price of the book.   | `49.90`                    |
diff --git a/api-documentation/datastructures/datastructures.md b/api-documentation/datastructures/datastructures.md
@@ -0,0 +1,89 @@
+# Data Structures
+
+## date (string) YYYY-MM-DD
+## isbn (string) ISBN-13
+## tucanid (string) XX-XX-XXXX-XX
+
+<!-- TODO: To be updated. -->
+## account (object)
++ id: `0987` (required, number) - The ID of the account.
+
+## book (object)
++ id: `2444` (required, number) - The ID of the book.
++ isbn: `9783836218023` (required, isbn) - The ISBN of the book.
++ title: `Java ist auch eine Insel` (required, string) - The title of the book.
++ state: `AC` (enum[string]) - secured - The state of the book.
+    + Members
+        + `AC` - Accepted
+        + `RJ` - Rejected
+        + `PP` - Proposed
+        + `OL` - Obsolete
++ author: `Christian Ullenboom` (required, string) - The author of the book.
++ price: `49.90` (number) - secured - The price of the book.
+
+## order (object)
++ id: `5862` (required, number) - The ID of the order.
++ status: `AR` (enum[string]) - semi-secured - The status of the order.
+    + Members
+        + `PD` - Pending
+        + `OD` - Ordered
+        + `RJ` - Rejected
+        + `AR` - Arrived
++ hint: `Enough books available.` (optional, string) - A hint text including extended information about the status.
++ book (required, book) - The ordered book.
++ student (required, account) - The student who has ordered the book.
++ timeframe (required, timeframe) - The timeframe in which the book order can be changed/cancelled. At the end of the timeframe the order will be processed.
+
+## module (object)
++ id: `3234` (required, number) - The ID of the module.
++ cid: `20-00-0004-iv` (required, tucanid) - The course ID of TUCaN.
++ name: `Functional and Object-oriented Programming Concepts` (required, string) - The name of the course.
++ lastOffered (required, season) - The season this course was last offered.
++ literature (required, array[book]) - The recommened literature of this course.
+
+## modulereduced (object)
++ id: `3234` (required, number) - The ID of the module.
++ cid: `20-00-0004-iv` (required, tucanid) - The course ID of TUCaN.
++ name: `Functional and Object-oriented Programming Concepts` (required, string) - The name of the course.
++ lastOffered (required, season) - The season this course was last offered.
+
+<!-- TODO: To be updated. -->
+## season (object)
++ id: `2156` (required, number) - The ID of the season.
++ season: `W` (required, enum[string]) - The season.
+    + Members
+        + `W` - Winter term
+        + `S` - Summer term
++ year: `2017` (required, string) - The year of the season.
+
+## timeframe (object)
++ from: `2017-02-01` (required, date) - The from-date of the timeframe (inclusive).
++ to: `2017-03-01` (required, date) - The to-date of the timeframe (inclusive).
+
+
+
+# Group Data Structures
+
+## Classifier Explanation
+
+The 'Classifier' describes how an attribute has to be applied. The following classifiers are available and can be combined (with some exceptions):
+- `optional` The attribute does not have to exit. Cannot be combined with `required`.
+- `required` The attribute has to exist. Cannot be combined with `optional`.
+- `secured` The attribute may only be read by administrators. Cannot be combined with `semi-secured`.
+- `semi-secured` The attribute may only be read by administrators and users that are strongly coupled to the object. Cannot be combined with `secured`.
+- `transient` The attribute is not stored and is calculated on demand by the server. Therefore it is not required to set this attribute when sending an object to the server.
+
+If neither `optional` nor `required` are set either `secured` or `semi-secured` have to be set.
+
+If either `secured` or `semi-secured` have been set, the following rules apply:
+- If the user is not permitted to see the attribute it must not be available (really not set, not even `null` or `undefined`).
+- If the user is permitted to see the attribute and neither `optional` nor `required` are set it must be available.
+- If the user is permitted to see the attribute and either `optional` or `required` are set, these rules apply.
+
+<!-- include(account.md) -->
+<!-- include(basic.md) -->
+<!-- include(book.md) -->
+<!-- include(module.md) -->
+<!-- include(order.md) -->
+<!-- include(season.md) -->
+<!-- include(timeframe.md) -->
diff --git a/api-documentation/datastructures/module.md b/api-documentation/datastructures/module.md
@@ -0,0 +1,15 @@
+## Book
+
+| Attribute   | Type        | Classifier | Description                               | Example                                               |
+|-------------|-------------|------------|-------------------------------------------|-------------------------------------------------------|
+| id          | number      | required   | The ID of the module.                     | `3234`                                                |
+| cid         | tucanid     | required   | The course ID of TUCaN.                   | `20-00-0004-iv`                                       |
+| name        | string      | required   | The name of the course.                   | `Functional and Object-oriented Programming Concepts` |
+| lastOffered | season      | required   | The season this course was last offered.  | See `Season`.                                         |
+| literature  | array[book] | required   | The recommened literature of this course. | \[ See `Book`. \]                                     |
+
+
+
+## Book (Reduced)
+
+Like `Book`, but `literature` does not exist.
diff --git a/api-documentation/datastructures/order.md b/api-documentation/datastructures/order.md
@@ -0,0 +1,10 @@
+## Order
+
+| Attribute | Type                                                                     | Classifier   | Description                                                                                                              | Example                   |
+|-----------|--------------------------------------------------------------------------|--------------|--------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| id        | number                                                                   | required     | The ID of the order.                                                                                                     | `5862`                    |
+| status    | enum[string] { `PD` Pending, `OD` Ordered, `RJ` Rejected, `AR` Arrived } | semi-secured | The status of the order.                                                                                                 | `AR`                      |
+| hint      | string                                                                   | optional     | A hint text including extended information about the status.                                                             | `Enough books available.` |
+| book      | book                                                                     | required     | The ordered book.                                                                                                        | See `Book`.               |
+| student   | account                                                                  | required     | The student who has ordered the book.                                                                                    | See `Account`.            |
+| timeframe | timeframe                                                                | required     | The timeframe in which the book order can be changed/cancelled. At the end of the timeframe the order will be processed. | See `Timeframe`.          |
diff --git a/api-documentation/datastructures/season.md b/api-documentation/datastructures/season.md
@@ -0,0 +1,7 @@
+## Book
+
+| Attribute | Type                                              | Classifier | Description             | Example |
+|-----------|---------------------------------------------------|------------|-------------------------|---------|
+| id        | number                                            | required   | The ID of the season.   | `2156`  |
+| season    | enum[string] { `W` Winter term, `S` Summer term } | required   | The season.             | `W`     |
+| year      | string                                            | required   | The year of the season. | `2017`  |
diff --git a/api-documentation/datastructures/timeframe.md b/api-documentation/datastructures/timeframe.md
@@ -0,0 +1,6 @@
+## Timeframe
+
+| Attribute | Type | Classifier | Description                                 | Example      |
+|-----------|------|------------|---------------------------------------------|--------------|
+| from      | date | required   | The from-date of the timeframe (inclusive). | `2017-02-01` |
+| to        | date | required   | The to-date of the timeframe (inclusive).   | `2017-03-01` |
diff --git a/api-documentation/routes/account.md b/api-documentation/routes/account.md
@@ -0,0 +1,166 @@
+# Group Account
+
+
+
+
+## Account Management [/account]
+
+**Notice:** An account is bound to the currently logged in user. Therefore these operations may not return the same data for different users.
+
+
+
+### Retrieve Account [GET /account]
+
+**Functionality:** Retrieves the current account.
+
+**Security:** Requires an authenticated user.
+
+
++ Response 200 (application/json; charset=utf-8)
+
+    + Attributes
+        + account (required, account)
+
+    + Body
+
+
++ Response 401
+
+    **Send if:** The user is not authenticated.
+
+    + Body
+
+
++ Response 403
+
+    **Send if:** The user does not have the required permissions.
+
+    + Body
+
+
+
+### Modify Account [PATCH /account]
+
+**Functionality:** Changes the given properties of the current account.
+
+**Security:** Requires an authenticated user.
+
+
++ Request (application/json)
+    + Attributes
+        + account (required)
+            <!-- TODO: To be updated. -->
+
+
++ Response 200 (application/json; charset=utf-8)
+
+    + Attributes
+        + account (required, account)
+
+    + Body
+
+
++ Response 401
+
+    **Send if:** The user is not authenticated.
+
+    + Body
+
+
++ Response 403
+
+    **Send if:** The user does not have the required permissions.
+
+    + Body
+
+
++ Response 422
+
+    **Send if:** The given item cannot be processed (e.g. if it is invalid).
+
+    + Body
+
+
+
+### Delete Account Data [DELETE /account]
+
+**Functionality:** Deletes the data of the current account.
+
+**Security:** Requires an authenticated user.
+
+
++ Response 204 (application/json; charset=utf-8)
+
+    + Body
+
+
++ Response 401
+
+    **Send if:** The user is not authenticated.
+
+    + Body
+
+
++ Response 403
+
+    **Send if:** The user does not have the required permissions.
+
+    + Body
+
+
++ Response 422
+
+    **Send if:** The given item cannot be processed (e.g. if it is invalid).
+
+    + Body
+
+
+
+### Retrieve Orders [GET /account/orders{?page,limit,status,orderBy}]
+
+**Functionality:** Retrieves the orders of the current account matching the given criteria.
+
+**Security:** Requires an authenticated user.
+
+
++ Parameters
+    + page: `1` (optional, number) - pagination - The page to return. Defaults to `1`.
+    + limit: `10` (optional, number) - pagination - The number of items per page. Defaults to `10`.
+    + status: `OD` (optional, enum[string]) - A comma-separated list of states to filter for.
+        + `PD` Pending
+        + `OD` Ordered
+        + `RJ` Rejected
+        + `AR` Arrived
+    + orderBy: `status` (optional, enum[string]) - The field to order by. Defaults to no specific order.
+        + `status` Order by the status.
+        + `timeframe` Order by the timeframe.
+
+
++ Response 200 (application/json; charset=utf-8)
+
+    + Attributes
+        + orders (required, array[order])
+        + total: `10` (required, number)
+
+    + Body
+
+
++ Response 400
+
+    **Send if:** Wrong parameters where sent from the user.
+
+    + Body
+
+
++ Response 401
+
+    **Send if:** The user is not authenticated.
+
+    + Body
+
+
++ Response 403
+
+    **Send if:** The user does not have the required permissions.
+
+    + Body