From 85c6f6c22736207f29f490cd8916a28a020fbcac Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Tue, 24 Jan 2017 11:41:10 +0100 Subject: [PATCH 1/8] Added REST datatypes. --- api-documentation/api-documentation.md | 9 +++ api-documentation/datastructures/account.md | 5 ++ api-documentation/datastructures/basic.md | 7 +++ api-documentation/datastructures/book.md | 10 +++ .../datastructures/datastructures.md | 62 +++++++++++++++++++ api-documentation/datastructures/order.md | 10 +++ api-documentation/datastructures/timeframe.md | 6 ++ api-documentation/routes/routes.md | 0 8 files changed, 109 insertions(+) create mode 100644 api-documentation/api-documentation.md create mode 100644 api-documentation/datastructures/account.md create mode 100644 api-documentation/datastructures/basic.md create mode 100644 api-documentation/datastructures/book.md create mode 100644 api-documentation/datastructures/datastructures.md create mode 100644 api-documentation/datastructures/order.md create mode 100644 api-documentation/datastructures/timeframe.md create mode 100644 api-documentation/routes/routes.md diff --git a/api-documentation/api-documentation.md b/api-documentation/api-documentation.md new file mode 100644 index 0000000..a769008 --- /dev/null +++ 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 + + + diff --git a/api-documentation/datastructures/account.md b/api-documentation/datastructures/account.md new file mode 100644 index 0000000..449bf7e --- /dev/null +++ b/api-documentation/datastructures/account.md @@ -0,0 +1,5 @@ +## Account + +| Attribute | Type | Classifier | Description | Example | +|-----------|--------|------------|------------------------|---------| +| id | number | required | The ID of the account. | `0987` | diff --git a/api-documentation/datastructures/basic.md b/api-documentation/datastructures/basic.md new file mode 100644 index 0000000..ab92770 --- /dev/null +++ b/api-documentation/datastructures/basic.md @@ -0,0 +1,7 @@ +## Basic + +### Date +A date encoded in the format `YYYY-MM-DD`. + +### ISBN-13 +An ISBN-13 without the dashes. diff --git a/api-documentation/datastructures/book.md b/api-documentation/datastructures/book.md new file mode 100644 index 0000000..b7a2103 --- /dev/null +++ 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] | | The state of the book. | See `Book`. | +| author | string | required | The author of the book. | See `Account`. | +| price | number | | The price of the book. | See `Timeframe`. | diff --git a/api-documentation/datastructures/datastructures.md b/api-documentation/datastructures/datastructures.md new file mode 100644 index 0000000..dac19f2 --- /dev/null +++ b/api-documentation/datastructures/datastructures.md @@ -0,0 +1,62 @@ +# Data Structures + +## date (string) YYYY-MM-DD +## isbn (string) ISBN-13 + + +## 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. + + `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. + + `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. + +## 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. + + + + + + diff --git a/api-documentation/datastructures/order.md b/api-documentation/datastructures/order.md new file mode 100644 index 0000000..0ad7a88 --- /dev/null +++ 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] | 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/timeframe.md b/api-documentation/datastructures/timeframe.md new file mode 100644 index 0000000..47e1616 --- /dev/null +++ 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/routes.md b/api-documentation/routes/routes.md new file mode 100644 index 0000000..e69de29 From b853dca67f514052d160bd6f2cdae33134510224 Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Tue, 24 Jan 2017 15:11:41 +0100 Subject: [PATCH 2/8] Added some routes to the REST API documentation. --- api-documentation/datastructures/book.md | 6 +- .../datastructures/datastructures.md | 16 +- api-documentation/routes/books.md | 253 ++++++++++++++++++ api-documentation/routes/modules.md | 70 +++++ api-documentation/routes/routes.md | 1 + api-documentation/routes/sample.md | 70 +++++ 6 files changed, 412 insertions(+), 4 deletions(-) create mode 100644 api-documentation/routes/books.md create mode 100644 api-documentation/routes/modules.md create mode 100644 api-documentation/routes/sample.md diff --git a/api-documentation/datastructures/book.md b/api-documentation/datastructures/book.md index b7a2103..f592576 100644 --- a/api-documentation/datastructures/book.md +++ b/api-documentation/datastructures/book.md @@ -5,6 +5,6 @@ | 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] | | The state of the book. | See `Book`. | -| author | string | required | The author of the book. | See `Account`. | -| price | number | | The price of the book. | See `Timeframe`. | +| state | enum[string] | | 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 index dac19f2..bc2ae7b 100644 --- a/api-documentation/datastructures/datastructures.md +++ b/api-documentation/datastructures/datastructures.md @@ -17,7 +17,7 @@ + `PP` Proposed + `OL` Obsolete + author: `Christian Ullenboom` (required, string) - The author of the book. -+ price: 49.90 (number) - secured - The price of the book. ++ price: `49.90` (number) - secured - The price of the book. ## order (object) + id: `5862` (required, number) - The ID of the order. @@ -31,6 +31,20 @@ + 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. + +## season (object) ++ id: `2156` (required, number) - The ID of the season. ++ season: `W` (required, enum[string]) - The season. + + `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). diff --git a/api-documentation/routes/books.md b/api-documentation/routes/books.md new file mode 100644 index 0000000..a385b47 --- /dev/null +++ b/api-documentation/routes/books.md @@ -0,0 +1,253 @@ +# Group Books + + + + +## Multiple Books [/books] + + + +### Retrieve Books [GET /books{?page,limit,isbn,title,state,author,orderBy}] + +**Functionality:** Retrieves all books matching the given criteria. + + ++ 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`. + + isbn: `9783836218023` (optional, isbn) - The ISBN to filter for. + + title: `Java ist auch eine Insel` (optional, string) - The title to filter for. Represents a text search. + + state: `AC` (optional, enum[string]) - The state to filter for. + + `AC` Accepted + + `RJ` Rejected + + `PP` Proposed + + `OL` Obsolete + + author: `Christian Ullenboom` (optional, string) - The author to filter for. Represents a text search. + + orderBy: `author` (optional, enum[string]) - The field to order by. Defaults to no specific order. + + `isbn` Order by the ISBN. + + `title` Order by the title. + + `state` Order by the state. + + `author` Order by the author. + + ++ Response 200 (application/json; charset=utf-8) + + + Attributes + + books (required, array[book]) + + + Body + + ++ Response 400 + + **Send if:** Wrong parameters where sent from the user. + + + Body + + + +### Propose Book [PUT /books] + +**Functionality:** Proposes a new book that has to be approved by an administrator. If this endpoint. + +**Security:** Requires an authenticated user. + + ++ Request Create by ISBN (application/json) + + Attributes + + book (required) + + isbn: `9783836218023` (optional, isbn) + + ++ Request Create by Author/Title (application/json) + + Attributes + + book (required) + + title: `Java ist auch eine Insel` (optional, string) + + author: `Christian Ullenboom` (optional, string) + + ++ Response 201 (application/json; charset=utf-8) + + **Send if:** The book was created an accepted (this is only possible if the proposal was sent by an administrator). + + + Attributes + + book (required, book) + + + Body + + ++ Response 202 (application/json; charset=utf-8) + + **Send if:** The book was created and is waiting for approval. + + + Attributes + + book (required, book) + + + 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 404 + + **Send if:** The given book was not found. + + + Body + + ++ Response 409 + + **Send if:** The book already exists. + + + Body + + ++ Response 422 + + **Send if:** The given item cannot be processed (e.g. if it is invalid). + + + Body + + + + +## Specific Book [/books/{bookId}] + ++ Parameters + + bookId: `2444` (required, number) - The ID of the book. + + + +### Retrieve Book [GET /books/{bookId}] + +**Functionality:** Retrieves the specified book. + + ++ Parameters + + bookId: `2444` (required, number) - The ID of the book. + + ++ Response 200 (application/json; charset=utf-8) + + + Attributes + + book (required, book) + + + Body + + ++ Response 404 + + **Send if:** The specified book is not available. + + + Body + + + +### Modify Book [PATCH /books/{bookId}] + +**Functionality:** Changes the given properties of the specified book. + +**Security:** Requires an authenticated user with the role `admin`. + + ++ Parameters + + bookId: `2444` (required, number) - The ID of the book. + + ++ Request (application/json) + + Attributes + + isbn: `9783836218023` (optional, isbn) + + title: `Java ist auch eine Insel` (optional, string) + + state: `AC` (optional, enum[string]) + + `AC` Accepted + + `RJ` Rejected + + `PP` Proposed + + `OL` Obsolete + + author: `Christian Ullenboom` (optional, string) + + price: `49.90` (optional, number) + + ++ Response 200 (application/json; charset=utf-8) + + + Attributes + + book (required, book) + + + 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 404 + + **Send if:** The specified book is not available. + + + Body + + ++ Response 422 + + **Send if:** The given item cannot be processed (e.g. if it is invalid). + + + Body + + + +### Delete Book [DELETE /books/{bookId}] + +**Functionality:** Deletes the specified book. + +**Security:** Requires an authenticated user with the role `admin`. + + ++ Parameters + + bookId: `2444` (required, number) - The ID of the book. + + ++ Response 200 (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 diff --git a/api-documentation/routes/modules.md b/api-documentation/routes/modules.md new file mode 100644 index 0000000..a48adb9 --- /dev/null +++ b/api-documentation/routes/modules.md @@ -0,0 +1,70 @@ +# Group Modules + + + + +## Multiple Modules [/modules] + + + +### Retrieve Modules [GET /modules{?page,limit}] + +**Functionality:** N/A + +**Notice:** N/A + +**Security:** Requires an authenticated user. +**Security:** Requires an authenticated user with the role `admin`. + + ++ Parameters + + PARAMETER: `EXAMPLE` (optional,required, TYPE) - DESCRIPTION + + ++ Request (application/json) + + Attributes + + ATTRIBUTE (optional,required, TYPE) + + ++ Response CODE (application/json; charset=utf-8) + + **Send if:** SEND_IF + + + Attributes + + ATTRIBUTE (optional,required, TYPE) + + + 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 + + ++ Response 422 + + **Send if:** The given item cannot be processed (e.g. if it is invalid). + + + Body + + + +### next operation +## next section +# next group diff --git a/api-documentation/routes/routes.md b/api-documentation/routes/routes.md index e69de29..620579f 100644 --- a/api-documentation/routes/routes.md +++ b/api-documentation/routes/routes.md @@ -0,0 +1 @@ + diff --git a/api-documentation/routes/sample.md b/api-documentation/routes/sample.md new file mode 100644 index 0000000..fd32bf9 --- /dev/null +++ b/api-documentation/routes/sample.md @@ -0,0 +1,70 @@ +# Group GROUP + + + + +## SECTION [PATH] + + + +### OPERATION_TITLE [METHOD PATH] + +**Functionality:** N/A + +**Notice:** N/A + +**Security:** Requires an authenticated user. +**Security:** Requires an authenticated user with the role `admin`. + + ++ Parameters + + PARAMETER: `EXAMPLE` (optional,required, TYPE) - DESCRIPTION + + ++ Request (application/json) + + Attributes + + ATTRIBUTE (optional,required, TYPE) + + ++ Response CODE (application/json; charset=utf-8) + + **Send if:** SEND_IF + + + Attributes + + ATTRIBUTE (optional,required, TYPE) + + + 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 + + ++ Response 422 + + **Send if:** The given item cannot be processed (e.g. if it is invalid). + + + Body + + + +### next operation +## next section +# next group From b80b05f0df16d82c2c3d669090b6e1c8d512dec6 Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Tue, 24 Jan 2017 15:42:15 +0100 Subject: [PATCH 3/8] Added missing data structures module and season. --- api-documentation/datastructures/basic.md | 3 +++ api-documentation/datastructures/book.md | 16 ++++++++-------- .../datastructures/datastructures.md | 8 ++++++-- api-documentation/datastructures/module.md | 9 +++++++++ api-documentation/datastructures/order.md | 16 ++++++++-------- api-documentation/datastructures/season.md | 7 +++++++ 6 files changed, 41 insertions(+), 18 deletions(-) create mode 100644 api-documentation/datastructures/module.md create mode 100644 api-documentation/datastructures/season.md diff --git a/api-documentation/datastructures/basic.md b/api-documentation/datastructures/basic.md index ab92770..e6fc3e5 100644 --- a/api-documentation/datastructures/basic.md +++ b/api-documentation/datastructures/basic.md @@ -5,3 +5,6 @@ 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 index f592576..867cf26 100644 --- a/api-documentation/datastructures/book.md +++ b/api-documentation/datastructures/book.md @@ -1,10 +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] | | 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` | +| 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 index bc2ae7b..861a190 100644 --- a/api-documentation/datastructures/datastructures.md +++ b/api-documentation/datastructures/datastructures.md @@ -2,8 +2,9 @@ ## date (string) YYYY-MM-DD ## isbn (string) ISBN-13 +## tucanid (string) XX-XX-XXXX-XX - + ## account (object) + id: `0987` (required, number) - The ID of the account. @@ -38,6 +39,7 @@ + lastOffered (required, season) - The season this course was last offered. + literature (required, array[book]) - The recommened literature of this course. + ## season (object) + id: `2156` (required, number) - The ID of the season. + season: `W` (required, enum[string]) - The season. @@ -69,8 +71,10 @@ If either `secured` or `semi-secured` have been set, the following rules apply: - 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. - + + + diff --git a/api-documentation/datastructures/module.md b/api-documentation/datastructures/module.md new file mode 100644 index 0000000..9a8e54f --- /dev/null +++ b/api-documentation/datastructures/module.md @@ -0,0 +1,9 @@ +## 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`. \] | diff --git a/api-documentation/datastructures/order.md b/api-documentation/datastructures/order.md index 0ad7a88..7d16e71 100644 --- a/api-documentation/datastructures/order.md +++ b/api-documentation/datastructures/order.md @@ -1,10 +1,10 @@ ## Order -| Attribute | Type | Classifier | Description | Example | -|-----------|--------------|--------------|--------------------------------------------------------------------------------------------------------------------------|---------------------------| -| id | number | required | The ID of the order. | `5862` | -| status | enum[string] | 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`. | +| 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 new file mode 100644 index 0000000..9ab286c --- /dev/null +++ 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` | From 9164add3025e1374518d959667350de5bccdafa3 Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Wed, 25 Jan 2017 14:25:09 +0100 Subject: [PATCH 4/8] "Finished" documentation. --- api-documentation/api-documentation.html | 1736 +++++++++++++++++ api-documentation/datastructures/account.md | 4 +- .../datastructures/datastructures.md | 6 + api-documentation/datastructures/module.md | 6 + api-documentation/routes/account.md | 166 ++ api-documentation/routes/books.md | 24 +- api-documentation/routes/modules.md | 178 +- api-documentation/routes/orders.md | 163 ++ api-documentation/routes/routes.md | 3 + 9 files changed, 2261 insertions(+), 25 deletions(-) create mode 100644 api-documentation/api-documentation.html create mode 100644 api-documentation/routes/account.md create mode 100644 api-documentation/routes/orders.md diff --git a/api-documentation/api-documentation.html b/api-documentation/api-documentation.html new file mode 100644 index 0000000..e81f959 --- /dev/null +++ b/api-documentation/api-documentation.html @@ -0,0 +1,1736 @@ +pyBuchaktion Back to top

pyBuchaktion

pyBuchaktion REST API Documentation Version 1.0

+

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.

    +
    • +
+

Account

+ + + + + + + + + + + + + + + + + + + + +
AttributeTypeClassifierDescriptionExample
idnumberrequiredThe ID of the account.1987
+

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).

+

Book

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeTypeClassifierDescriptionExample
idnumberrequiredThe ID of the book.2444
isbnisbnrequiredThe status of the order.9783836218023
titlestringrequiredThe title of the book.Java ist auch eine Insel
stateenum[string] { AC Accepted, RJ Rejected, PP Proposed, OL Obsolete }The state of the book.AC
authorstringrequiredThe author of the book.Christian Ullenboom
pricenumberThe price of the book.49.90
+

Book

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeTypeClassifierDescriptionExample
idnumberrequiredThe ID of the module.3234
cidtucanidrequiredThe course ID of TUCaN.20-00-0004-iv
namestringrequiredThe name of the course.Functional and Object-oriented Programming Concepts
lastOfferedseasonrequiredThe season this course was last offered.See Season.
literaturearray[book]requiredThe recommened literature of this course.[ See Book. ]
+

Book (Reduced)

+

Like Book, but literature does not exist.

+

Order

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeTypeClassifierDescriptionExample
idnumberrequiredThe ID of the order.5862
statusenum[string] { PD Pending, OD Ordered, RJ Rejected, AR Arrived }semi-securedThe status of the order.AR
hintstringoptionalA hint text including extended information about the status.Enough books available.
bookbookrequiredThe ordered book.See Book.
studentaccountrequiredThe student who has ordered the book.See Account.
timeframetimeframerequiredThe timeframe in which the book order can be changed/cancelled. At the end of the timeframe the order will be processed.See Timeframe.
+

Book

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeTypeClassifierDescriptionExample
idnumberrequiredThe ID of the season.2156
seasonenum[string] { W Winter term, S Summer term }requiredThe season.W
yearstringrequiredThe year of the season.2017
+

Timeframe

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeTypeClassifierDescriptionExample
fromdaterequiredThe from-date of the timeframe (inclusive).2017-02-01
todaterequiredThe to-date of the timeframe (inclusive).2017-03-01
+

Account

Account Management

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.

+

Example URI

GET https://www.d120.de/studierende/buchaktion/api/account
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "account": {
+    "id": 987
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "account": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the account."
+        }
+      },
+      "required": [
+        "id"
+      ]
+    }
+  },
+  "required": [
+    "account"
+  ]
+}
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+

Modify Account
PATCH/account

Functionality: Changes the given properties of the current account.

+

Security: Requires an authenticated user.

+

Example URI

PATCH https://www.d120.de/studierende/buchaktion/api/account
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "account": "Hello, world!"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "account": {
+      "type": "string",
+      "description": "<!-- TODO: To be updated. -->"
+    }
+  },
+  "required": [
+    "account"
+  ]
+}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "account": {
+    "id": 987
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "account": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the account."
+        }
+      },
+      "required": [
+        "id"
+      ]
+    }
+  },
+  "required": [
+    "account"
+  ]
+}
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Delete Account Data
DELETE/account

Functionality: Deletes the data of the current account.

+

Security: Requires an authenticated user.

+

Example URI

DELETE https://www.d120.de/studierende/buchaktion/api/account
Response  204
HideShow
Headers
Content-Type: application/json; charset=utf-8
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

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.

+

Example URI

GET https://www.d120.de/studierende/buchaktion/api/account/orders?page=1&limit=10&status=OD&orderBy=status
URI Parameters
HideShow
page
number (optional) Example: 1

pagination - The page to return. Defaults to 1.

+
limit
number (optional) Example: 10

pagination - The number of items per page. Defaults to 10.

+
status
string (optional) Example: OD

A comma-separated list of states to filter for.

+
    +
  • +

    PD Pending

    +
    • +
  • +

    OD Ordered

    +
    • +
  • +

    RJ Rejected

    +
    • +
  • +

    AR Arrived

    +
    • +
+
orderBy
string (optional) Example: status

The field to order by. Defaults to no specific order.

+
    +
  • +

    status Order by the status.

    +
    • +
  • +

    timeframe Order by the timeframe.

    +
    • +
+
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "orders": [
+    {
+      "id": 5862,
+      "status": "AR",
+      "hint": "Enough books available.",
+      "book": {
+        "id": 2444,
+        "isbn": "9783836218023",
+        "title": "Java ist auch eine Insel",
+        "state": "AC",
+        "author": "Christian Ullenboom",
+        "price": 49.9
+      },
+      "student": {
+        "id": 987
+      },
+      "timeframe": {
+        "from": "2017-02-01",
+        "to": "2017-03-01"
+      }
+    }
+  ],
+  "total": 10
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "orders": {
+      "type": "array"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "orders",
+    "total"
+  ]
+}
Response  400
HideShow

Send if: Wrong parameters where sent from the user.

+
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+

Books

Multiple Books

Retrieve Books
GET/books{?page,limit,isbn,title,state,author,orderBy}

Functionality: Retrieves all books matching the given criteria.

+

Example URI

GET https://www.d120.de/studierende/buchaktion/api/books?page=1&limit=10&isbn=9783836218023&title=java&state=AC&author=ullenboom&orderBy=author
URI Parameters
HideShow
page
number (optional) Example: 1

pagination - The page to return. Defaults to 1.

+
limit
number (optional) Example: 10

pagination - The number of items per page. Defaults to 10.

+
isbn
isbn (optional) Example: 9783836218023

A comma-separated list of ISBNs to filter for.

+
title
string (optional) Example: java

The title to filter for. Represents a case-insensitive text search.

+
state
string (optional) Example: AC

A comma-separated list of states to filter for.

+
    +
  • +

    AC Accepted

    +
    • +
  • +

    RJ Rejected

    +
    • +
  • +

    PP Proposed

    +
    • +
  • +

    OL Obsolete

    +
    • +
+
author
string (optional) Example: ullenboom

The author to filter for. Represents a case-insensitive text search.

+
orderBy
string (optional) Example: author

The field to order by. Defaults to no specific order.

+
    +
  • +

    isbn Order by the ISBN.

    +
    • +
  • +

    title Order by the title.

    +
    • +
  • +

    state Order by the state.

    +
    • +
  • +

    author Order by the author.

    +
    • +
+
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "books": [
+    {
+      "id": 2444,
+      "isbn": "9783836218023",
+      "title": "Java ist auch eine Insel",
+      "state": "AC",
+      "author": "Christian Ullenboom",
+      "price": 49.9
+    }
+  ],
+  "total": 10
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "books": {
+      "type": "array"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "books",
+    "total"
+  ]
+}
Response  400
HideShow

Send if: Wrong parameters where sent from the user.

+

Propose Book
PUT/books

Functionality: Proposes a new book that has to be approved by an administrator. If this endpoint.

+

Security: Requires an authenticated user.

+

Example URI

PUT https://www.d120.de/studierende/buchaktion/api/books
Request  Create by ISBN
HideShow
Headers
Content-Type: application/json
Body
{
+  "book": {
+    "isbn": "9783836218023"
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "book": {
+      "type": "object",
+      "properties": {
+        "isbn": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required": [
+    "book"
+  ]
+}
Request  Create by Author/Title
HideShow
Headers
Content-Type: application/json
Body
{
+  "book": {
+    "title": "Java ist auch eine Insel",
+    "author": "Christian Ullenboom"
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "book": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string"
+        },
+        "author": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required": [
+    "book"
+  ]
+}
Response  201
HideShow

Send if: The book was created an accepted (this is only possible if the proposal was sent by an administrator).

+
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "book": {
+    "id": 2444,
+    "isbn": "9783836218023",
+    "title": "Java ist auch eine Insel",
+    "state": "AC",
+    "author": "Christian Ullenboom",
+    "price": 49.9
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "book": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the book."
+        },
+        "isbn": {
+          "type": "string",
+          "description": "The ISBN of the book."
+        },
+        "title": {
+          "type": "string",
+          "description": "The title of the book."
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "`AC` Accepted",
+            "`RJ` Rejected",
+            "`PP` Proposed",
+            "`OL` Obsolete"
+          ],
+          "description": "secured - The state of the book."
+        },
+        "author": {
+          "type": "string",
+          "description": "The author of the book."
+        },
+        "price": {
+          "type": "number",
+          "description": "secured - The price of the book."
+        }
+      },
+      "required": [
+        "id",
+        "isbn",
+        "title",
+        "author"
+      ]
+    }
+  },
+  "required": [
+    "book"
+  ]
+}
Response  202
HideShow

Send if: The book was created and is waiting for approval.

+
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "book": {
+    "id": 2444,
+    "isbn": "9783836218023",
+    "title": "Java ist auch eine Insel",
+    "state": "AC",
+    "author": "Christian Ullenboom",
+    "price": 49.9
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "book": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the book."
+        },
+        "isbn": {
+          "type": "string",
+          "description": "The ISBN of the book."
+        },
+        "title": {
+          "type": "string",
+          "description": "The title of the book."
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "`AC` Accepted",
+            "`RJ` Rejected",
+            "`PP` Proposed",
+            "`OL` Obsolete"
+          ],
+          "description": "secured - The state of the book."
+        },
+        "author": {
+          "type": "string",
+          "description": "The author of the book."
+        },
+        "price": {
+          "type": "number",
+          "description": "secured - The price of the book."
+        }
+      },
+      "required": [
+        "id",
+        "isbn",
+        "title",
+        "author"
+      ]
+    }
+  },
+  "required": [
+    "book"
+  ]
+}
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  404
HideShow

Send if: The specified book was not found.

+
Response  409
HideShow

Send if: The book already exists.

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Specific Book

Retrieve Book
GET/books/{bookId}

Functionality: Retrieves the specified book.

+

Example URI

GET https://www.d120.de/studierende/buchaktion/api/books/2444
URI Parameters
HideShow
bookId
number (required) Example: 2444

The ID of the book.

+
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "book": {
+    "id": 2444,
+    "isbn": "9783836218023",
+    "title": "Java ist auch eine Insel",
+    "state": "AC",
+    "author": "Christian Ullenboom",
+    "price": 49.9
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "book": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the book."
+        },
+        "isbn": {
+          "type": "string",
+          "description": "The ISBN of the book."
+        },
+        "title": {
+          "type": "string",
+          "description": "The title of the book."
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "`AC` Accepted",
+            "`RJ` Rejected",
+            "`PP` Proposed",
+            "`OL` Obsolete"
+          ],
+          "description": "secured - The state of the book."
+        },
+        "author": {
+          "type": "string",
+          "description": "The author of the book."
+        },
+        "price": {
+          "type": "number",
+          "description": "secured - The price of the book."
+        }
+      },
+      "required": [
+        "id",
+        "isbn",
+        "title",
+        "author"
+      ]
+    }
+  },
+  "required": [
+    "book"
+  ]
+}
Response  404
HideShow

Send if: The specified book was not found

+

Modify Book
PATCH/books/{bookId}

Functionality: Changes the given properties of the specified book.

+

Security: Requires an authenticated user with the role admin.

+

Example URI

PATCH https://www.d120.de/studierende/buchaktion/api/books/2444
URI Parameters
HideShow
bookId
number (required) Example: 2444

The ID of the book.

+
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "isbn": "9783836218023",
+  "title": "Java ist auch eine Insel",
+  "state": "AC",
+  "author": "Christian Ullenboom",
+  "price": 49.9
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "isbn": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "`AC` Accepted",
+        "`RJ` Rejected",
+        "`PP` Proposed",
+        "`OL` Obsolete"
+      ]
+    },
+    "author": {
+      "type": "string"
+    },
+    "price": {
+      "type": "number"
+    }
+  }
+}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "book": {
+    "id": 2444,
+    "isbn": "9783836218023",
+    "title": "Java ist auch eine Insel",
+    "state": "AC",
+    "author": "Christian Ullenboom",
+    "price": 49.9
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "book": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the book."
+        },
+        "isbn": {
+          "type": "string",
+          "description": "The ISBN of the book."
+        },
+        "title": {
+          "type": "string",
+          "description": "The title of the book."
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "`AC` Accepted",
+            "`RJ` Rejected",
+            "`PP` Proposed",
+            "`OL` Obsolete"
+          ],
+          "description": "secured - The state of the book."
+        },
+        "author": {
+          "type": "string",
+          "description": "The author of the book."
+        },
+        "price": {
+          "type": "number",
+          "description": "secured - The price of the book."
+        }
+      },
+      "required": [
+        "id",
+        "isbn",
+        "title",
+        "author"
+      ]
+    }
+  },
+  "required": [
+    "book"
+  ]
+}
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  404
HideShow

Send if: The specified book was not found

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Delete Book
DELETE/books/{bookId}

Functionality: Deletes the specified book.

+

Security: Requires an authenticated user with the role admin.

+

Example URI

DELETE https://www.d120.de/studierende/buchaktion/api/books/2444
URI Parameters
HideShow
bookId
number (required) Example: 2444

The ID of the book.

+
Response  204
HideShow
Headers
Content-Type: application/json; charset=utf-8
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  404
HideShow

Send if: The specified book was not found

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Modules

Multiple Modules

Retrieve Modules
GET/modules{?page,limit,cid,name}

Functionality: Retrieves all modules matching the given criteria.

+

Example URI

GET https://www.d120.de/studierende/buchaktion/api/modules?page=1&limit=10&cid=20-00-0004-iv&name=programming
URI Parameters
HideShow
page
number (optional) Example: 1

pagination - The page to return. Defaults to 1.

+
limit
number (optional) Example: 10

pagination - The number of items per page. Defaults to 10.

+
cid
tucanid (optional) Example: 20-00-0004-iv

A comma-separated list of TUCaN course IDs to filter for.

+
name
string (optional) Example: programming

The course name to filter for. Represents a case-insensitive text search.

+
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "modules": [
+    {
+      "id": 3234,
+      "cid": "20-00-0004-iv",
+      "name": "Functional and Object-oriented Programming Concepts",
+      "lastOffered": {
+        "id": 2156,
+        "season": "W",
+        "year": "2017"
+      }
+    }
+  ],
+  "total": 0
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "modules": {
+      "type": "array"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "modules",
+    "total"
+  ]
+}
Response  400
HideShow

Send if: Wrong parameters where sent from the user.

+

Create Module
PUT/modules

Functionality: Creates a new module.

+

Security: Requires an authenticated user with the role admin.

+

Example URI

PUT https://www.d120.de/studierende/buchaktion/api/modules
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "module": {
+    "cid": "20-00-0004-iv",
+    "name": "Functional and Object-oriented Programming Concepts",
+    "lastOffered": {
+      "id": 2156,
+      "season": "W",
+      "year": "2017"
+    },
+    "literature": []
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "module": {
+      "type": "object",
+      "properties": {
+        "cid": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "lastOffered": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The ID of the season."
+            },
+            "season": {
+              "type": "string",
+              "enum": [
+                "`W` Winter term",
+                "`S` Summer term"
+              ],
+              "description": "The season."
+            },
+            "year": {
+              "type": "string",
+              "description": "The year of the season."
+            }
+          },
+          "required": [
+            "id",
+            "season",
+            "year"
+          ]
+        },
+        "literature": {
+          "type": "array",
+          "description": "The IDs of the proposed books."
+        }
+      },
+      "required": [
+        "cid",
+        "name",
+        "lastOffered"
+      ]
+    }
+  },
+  "required": [
+    "module"
+  ]
+}
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "module": {
+    "id": 3234,
+    "cid": "20-00-0004-iv",
+    "name": "Functional and Object-oriented Programming Concepts",
+    "lastOffered": {
+      "id": 2156,
+      "season": "W",
+      "year": "2017"
+    },
+    "literature": [
+      {
+        "id": 2444,
+        "isbn": "9783836218023",
+        "title": "Java ist auch eine Insel",
+        "state": "AC",
+        "author": "Christian Ullenboom",
+        "price": 49.9
+      }
+    ]
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "module": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the module."
+        },
+        "cid": {
+          "type": "string",
+          "description": "The course ID of TUCaN."
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the course."
+        },
+        "lastOffered": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The ID of the season."
+            },
+            "season": {
+              "type": "string",
+              "enum": [
+                "`W` Winter term",
+                "`S` Summer term"
+              ],
+              "description": "The season."
+            },
+            "year": {
+              "type": "string",
+              "description": "The year of the season."
+            }
+          },
+          "required": [
+            "id",
+            "season",
+            "year"
+          ],
+          "description": "The season this course was last offered."
+        },
+        "literature": {
+          "type": "array",
+          "description": "The recommened literature of this course."
+        }
+      },
+      "required": [
+        "id",
+        "cid",
+        "name",
+        "lastOffered",
+        "literature"
+      ]
+    }
+  },
+  "required": [
+    "module"
+  ]
+}
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Specific Moudle

Retrieve Module
GET/modules/{moduleId}

Functionality: Retrieves the specified module.

+

Example URI

GET https://www.d120.de/studierende/buchaktion/api/modules/3234
URI Parameters
HideShow
moduleId
number (required) Example: 3234

The ID of the module.

+
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "module": {
+    "id": 3234,
+    "cid": "20-00-0004-iv",
+    "name": "Functional and Object-oriented Programming Concepts",
+    "lastOffered": {
+      "id": 2156,
+      "season": "W",
+      "year": "2017"
+    },
+    "literature": [
+      {
+        "id": 2444,
+        "isbn": "9783836218023",
+        "title": "Java ist auch eine Insel",
+        "state": "AC",
+        "author": "Christian Ullenboom",
+        "price": 49.9
+      }
+    ]
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "module": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the module."
+        },
+        "cid": {
+          "type": "string",
+          "description": "The course ID of TUCaN."
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the course."
+        },
+        "lastOffered": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The ID of the season."
+            },
+            "season": {
+              "type": "string",
+              "enum": [
+                "`W` Winter term",
+                "`S` Summer term"
+              ],
+              "description": "The season."
+            },
+            "year": {
+              "type": "string",
+              "description": "The year of the season."
+            }
+          },
+          "required": [
+            "id",
+            "season",
+            "year"
+          ],
+          "description": "The season this course was last offered."
+        },
+        "literature": {
+          "type": "array",
+          "description": "The recommened literature of this course."
+        }
+      },
+      "required": [
+        "id",
+        "cid",
+        "name",
+        "lastOffered",
+        "literature"
+      ]
+    }
+  },
+  "required": [
+    "module"
+  ]
+}
Response  404
HideShow

Send if: The specified module was not found.

+

Modify Module
PATCH/modules/{moduleId}

Functionality: Changes the given properties of the specified module.

+

Security: Requires an authenticated user with the role admin.

+

Example URI

PATCH https://www.d120.de/studierende/buchaktion/api/modules/3234
URI Parameters
HideShow
moduleId
number (required) Example: 3234

The ID of the module.

+
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "module": {
+    "cid": "20-00-0004-iv",
+    "name": "Functional and Object-oriented Programming Concepts",
+    "lastOffered": {
+      "id": 2156,
+      "season": "W",
+      "year": "2017"
+    },
+    "literature": []
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "module": {
+      "type": "object",
+      "properties": {
+        "cid": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "lastOffered": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The ID of the season."
+            },
+            "season": {
+              "type": "string",
+              "enum": [
+                "`W` Winter term",
+                "`S` Summer term"
+              ],
+              "description": "The season."
+            },
+            "year": {
+              "type": "string",
+              "description": "The year of the season."
+            }
+          },
+          "required": [
+            "id",
+            "season",
+            "year"
+          ]
+        },
+        "literature": {
+          "type": "array",
+          "description": "The IDs of the proposed books."
+        }
+      }
+    }
+  },
+  "required": [
+    "module"
+  ]
+}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "module": {
+    "id": 3234,
+    "cid": "20-00-0004-iv",
+    "name": "Functional and Object-oriented Programming Concepts",
+    "lastOffered": {
+      "id": 2156,
+      "season": "W",
+      "year": "2017"
+    },
+    "literature": [
+      {
+        "id": 2444,
+        "isbn": "9783836218023",
+        "title": "Java ist auch eine Insel",
+        "state": "AC",
+        "author": "Christian Ullenboom",
+        "price": 49.9
+      }
+    ]
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "module": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the module."
+        },
+        "cid": {
+          "type": "string",
+          "description": "The course ID of TUCaN."
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the course."
+        },
+        "lastOffered": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The ID of the season."
+            },
+            "season": {
+              "type": "string",
+              "enum": [
+                "`W` Winter term",
+                "`S` Summer term"
+              ],
+              "description": "The season."
+            },
+            "year": {
+              "type": "string",
+              "description": "The year of the season."
+            }
+          },
+          "required": [
+            "id",
+            "season",
+            "year"
+          ],
+          "description": "The season this course was last offered."
+        },
+        "literature": {
+          "type": "array",
+          "description": "The recommened literature of this course."
+        }
+      },
+      "required": [
+        "id",
+        "cid",
+        "name",
+        "lastOffered",
+        "literature"
+      ]
+    }
+  },
+  "required": [
+    "module"
+  ]
+}
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  404
HideShow

Send if: The specified module was not found.

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Delete Module
DELETE/modules/{moduleId}

Functionality: Deletes the specified module.

+

Security: Requires an authenticated user with the role admin.

+

Example URI

DELETE https://www.d120.de/studierende/buchaktion/api/modules/3234
URI Parameters
HideShow
moduleId
number (required) Example: 3234

The ID of the module.

+
Response  204
HideShow
Headers
Content-Type: application/json; charset=utf-8
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  404
HideShow

Send if: The specified module was not found.

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Orders

Multiple Orders

Retrieve Orders
GET/orders{?page,limit,userId,status,orderBy}

Functionality: Retrieves all orders that are visible to the current user (that is, only the orders of the logged in user or all orders if the logged in user as the role admin).

+

Security: Requires an authenticated user.

+

Example URI

GET https://www.d120.de/studierende/buchaktion/api/orders?page=1&limit=10&userId=1987&status=OD&orderBy=status
URI Parameters
HideShow
page
number (optional) Example: 1

pagination - The page to return. Defaults to 1.

+
limit
number (optional) Example: 10

pagination - The number of items per page. Defaults to 10.

+
userId
number (optional) Example: 1987

A comma-separated list of user IDs to filter for. This property does not have any functionality if the current user does not have the role admin.

+
status
string (optional) Example: OD

A comma-separated list of states to filter for.

+
    +
  • +

    PD Pending

    +
    • +
  • +

    OD Ordered

    +
    • +
  • +

    RJ Rejected

    +
    • +
  • +

    AR Arrived

    +
    • +
+
orderBy
string (optional) Example: status

The field to order by. Defaults to no specific order.

+
    +
  • +

    status Order by the status.

    +
    • +
  • +

    timeframe Order by the timeframe.

    +
    • +
+
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "orders": [
+    {
+      "id": 5862,
+      "status": "AR",
+      "hint": "Enough books available.",
+      "book": {
+        "id": 2444,
+        "isbn": "9783836218023",
+        "title": "Java ist auch eine Insel",
+        "state": "AC",
+        "author": "Christian Ullenboom",
+        "price": 49.9
+      },
+      "student": {
+        "id": 987
+      },
+      "timeframe": {
+        "from": "2017-02-01",
+        "to": "2017-03-01"
+      }
+    }
+  ],
+  "total": 10
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "orders": {
+      "type": "array"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "orders",
+    "total"
+  ]
+}
Response  400
HideShow

Send if: Wrong parameters where sent from the user.

+
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+

Specific Order

Modify Order
PATCH/orders/{orderId}

Functionality: Changes the given properties of the specified order.

+

Security: Requires an authenticated user with the role admin.

+

Example URI

PATCH https://www.d120.de/studierende/buchaktion/api/orders/5862
URI Parameters
HideShow
orderId
number (required) Example: 5862

The ID of the order.

+
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "order": {
+    "status": "`PD` Pending",
+    "hint": "Enough books available."
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "order": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "`PD` Pending",
+            "`OD` Ordered",
+            "`RJ` Rejected",
+            "`AR` Arrived"
+          ]
+        },
+        "hint": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required": [
+    "order"
+  ]
+}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
+  "order": {
+    "id": 5862,
+    "status": "AR",
+    "hint": "Enough books available.",
+    "book": {
+      "id": 2444,
+      "isbn": "9783836218023",
+      "title": "Java ist auch eine Insel",
+      "state": "AC",
+      "author": "Christian Ullenboom",
+      "price": 49.9
+    },
+    "student": {
+      "id": 987
+    },
+    "timeframe": {
+      "from": "2017-02-01",
+      "to": "2017-03-01"
+    }
+  }
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "order": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the order."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "`PD` Pending",
+            "`OD` Ordered",
+            "`RJ` Rejected",
+            "`AR` Arrived"
+          ],
+          "description": "semi-secured - The status of the order."
+        },
+        "hint": {
+          "type": "string",
+          "description": "A hint text including extended information about the status."
+        },
+        "book": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The ID of the book."
+            },
+            "isbn": {
+              "type": "string",
+              "description": "The ISBN of the book."
+            },
+            "title": {
+              "type": "string",
+              "description": "The title of the book."
+            },
+            "state": {
+              "type": "string",
+              "enum": [
+                "`AC` Accepted",
+                "`RJ` Rejected",
+                "`PP` Proposed",
+                "`OL` Obsolete"
+              ],
+              "description": "secured - The state of the book."
+            },
+            "author": {
+              "type": "string",
+              "description": "The author of the book."
+            },
+            "price": {
+              "type": "number",
+              "description": "secured - The price of the book."
+            }
+          },
+          "required": [
+            "id",
+            "isbn",
+            "title",
+            "author"
+          ],
+          "description": "The ordered book."
+        },
+        "student": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The ID of the account."
+            }
+          },
+          "required": [
+            "id"
+          ],
+          "description": "The student who has ordered the book."
+        },
+        "timeframe": {
+          "type": "object",
+          "properties": {
+            "from": {
+              "type": "string",
+              "description": "The from-date of the timeframe (inclusive)."
+            },
+            "to": {
+              "type": "string",
+              "description": "The to-date of the timeframe (inclusive)."
+            }
+          },
+          "required": [
+            "from",
+            "to"
+          ],
+          "description": "The timeframe in which the book order can be changed/cancelled. At the end of the timeframe the order will be processed."
+        }
+      },
+      "required": [
+        "id",
+        "book",
+        "student",
+        "timeframe"
+      ]
+    }
+  },
+  "required": [
+    "order"
+  ]
+}
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  404
HideShow

Send if: The specified order was not found.

+
Response  422
HideShow

Send if: The given item cannot be processed (e.g. if it is invalid).

+

Delete Order
DELETE/orders/{orderId}

Functionality: Deletes the specified order.

+

Security: Requires an authenticated user with the role admin or the user who has created the order.

+

Example URI

DELETE https://www.d120.de/studierende/buchaktion/api/orders/5862
URI Parameters
HideShow
orderId
number (required) Example: 5862

The ID of the order.

+
Response  204
HideShow
Headers
Content-Type: application/json; charset=utf-8
Response  401
HideShow

Send if: The user is not authenticated.

+
Response  403
HideShow

Send if: The user does not have the required permissions.

+
Response  404
HideShow

Send if: The specified order was not found.

+

Generated by aglio on 25 Jan 2017

\ No newline at end of file diff --git a/api-documentation/datastructures/account.md b/api-documentation/datastructures/account.md index 449bf7e..a0438a2 100644 --- a/api-documentation/datastructures/account.md +++ b/api-documentation/datastructures/account.md @@ -1,5 +1,7 @@ ## Account + + | Attribute | Type | Classifier | Description | Example | |-----------|--------|------------|------------------------|---------| -| id | number | required | The ID of the account. | `0987` | +| id | number | required | The ID of the account. | `1987` | diff --git a/api-documentation/datastructures/datastructures.md b/api-documentation/datastructures/datastructures.md index 861a190..9f71293 100644 --- a/api-documentation/datastructures/datastructures.md +++ b/api-documentation/datastructures/datastructures.md @@ -39,6 +39,12 @@ + 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. + ## season (object) + id: `2156` (required, number) - The ID of the season. diff --git a/api-documentation/datastructures/module.md b/api-documentation/datastructures/module.md index 9a8e54f..8405eff 100644 --- a/api-documentation/datastructures/module.md +++ b/api-documentation/datastructures/module.md @@ -7,3 +7,9 @@ | 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/routes/account.md b/api-documentation/routes/account.md new file mode 100644 index 0000000..a874edf --- /dev/null +++ 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) + + + ++ 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 diff --git a/api-documentation/routes/books.md b/api-documentation/routes/books.md index a385b47..d42b038 100644 --- a/api-documentation/routes/books.md +++ b/api-documentation/routes/books.md @@ -15,14 +15,14 @@ + 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`. - + isbn: `9783836218023` (optional, isbn) - The ISBN to filter for. - + title: `Java ist auch eine Insel` (optional, string) - The title to filter for. Represents a text search. - + state: `AC` (optional, enum[string]) - The state to filter for. + + isbn: `9783836218023` (optional, isbn) - A comma-separated list of ISBNs to filter for. + + title: `java` (optional, string) - The title to filter for. Represents a case-insensitive text search. + + state: `AC` (optional, enum[string]) - A comma-separated list of states to filter for. + `AC` Accepted + `RJ` Rejected + `PP` Proposed + `OL` Obsolete - + author: `Christian Ullenboom` (optional, string) - The author to filter for. Represents a text search. + + author: `ullenboom` (optional, string) - The author to filter for. Represents a case-insensitive text search. + orderBy: `author` (optional, enum[string]) - The field to order by. Defaults to no specific order. + `isbn` Order by the ISBN. + `title` Order by the title. @@ -34,6 +34,7 @@ + Attributes + books (required, array[book]) + + total: `10` (required, number) + Body @@ -102,7 +103,7 @@ + Response 404 - **Send if:** The given book was not found. + **Send if:** The specified book was not found. + Body @@ -149,7 +150,7 @@ + Response 404 - **Send if:** The specified book is not available. + **Send if:** The specified book was not found + Body @@ -203,7 +204,7 @@ + Response 404 - **Send if:** The specified book is not available. + **Send if:** The specified book was not found + Body @@ -227,7 +228,7 @@ + bookId: `2444` (required, number) - The ID of the book. -+ Response 200 (application/json; charset=utf-8) ++ Response 204 (application/json; charset=utf-8) + Body @@ -246,6 +247,13 @@ + Body ++ Response 404 + + **Send if:** The specified book was not found + + + Body + + + Response 422 **Send if:** The given item cannot be processed (e.g. if it is invalid). diff --git a/api-documentation/routes/modules.md b/api-documentation/routes/modules.md index a48adb9..c40bbec 100644 --- a/api-documentation/routes/modules.md +++ b/api-documentation/routes/modules.md @@ -7,38 +7,138 @@ -### Retrieve Modules [GET /modules{?page,limit}] +### Retrieve Modules [GET /modules{?page,limit,cid,name}] -**Functionality:** N/A +**Functionality:** Retrieves all modules matching the given criteria. -**Notice:** N/A -**Security:** Requires an authenticated user. -**Security:** Requires an authenticated user with the role `admin`. ++ 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`. + + cid: `20-00-0004-iv` (optional, tucanid) - A comma-separated list of TUCaN course IDs to filter for. + + name: `programming` (optional, string) - The course name to filter for. Represents a case-insensitive text search. + + ++ Response 200 (application/json; charset=utf-8) + + + Attributes + + modules (required, array[modulereduced]) + + total (required, number) + + + Body + + ++ Response 400 + + **Send if:** Wrong parameters where sent from the user. + + + Body -+ Parameters - + PARAMETER: `EXAMPLE` (optional,required, TYPE) - DESCRIPTION + +### Create Module [PUT /modules] + +**Functionality:** Creates a new module. + +**Security:** Requires an authenticated user with the role `admin`. + Request (application/json) + Attributes - + ATTRIBUTE (optional,required, TYPE) + + module (required) + + cid: `20-00-0004-iv` (required, tucanid) + + name: `Functional and Object-oriented Programming Concepts` (required, string) + + lastOffered (required, season) + + literature (optional, array[string]) - The IDs of the proposed books. -+ Response CODE (application/json; charset=utf-8) ++ Response 201 (application/json; charset=utf-8) + + + Attributes + + module (required, module) + + + Body + + ++ Response 401 + + **Send if:** The user is not authenticated. + + + Body - **Send if:** SEND_IF + ++ 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 + + + + +## Specific Moudle [/modules/{moduleId}] + ++ Parameters + + moduleId: `3234` (required, number) - The ID of the module. + + + +### Retrieve Module [GET /modules/{moduleId}] + +**Functionality:** Retrieves the specified module. + + ++ Parameters + + moduleId: `3234` (required, number) - The ID of the module. + + ++ Response 200 (application/json; charset=utf-8) + Attributes - + ATTRIBUTE (optional,required, TYPE) + + module (required, module) + Body -+ Response 400 ++ Response 404 - **Send if:** Wrong parameters where sent from the user. + **Send if:** The specified module was not found. + + + Body + + + +### Modify Module [PATCH /modules/{moduleId}] + +**Functionality:** Changes the given properties of the specified module. + +**Security:** Requires an authenticated user with the role `admin`. + + ++ Parameters + + moduleId: `3234` (required, number) - The ID of the module. + + ++ Request (application/json) + + Attributes + + module (required) + + cid: `20-00-0004-iv` (optional, tucanid) + + name: `Functional and Object-oriented Programming Concepts` (optional, string) + + lastOffered (optional, season) + + literature (optional, array[string]) - The IDs of the proposed books. + + ++ Response 200 (application/json; charset=utf-8) + + + Attributes + + module (required, module) + Body @@ -57,6 +157,13 @@ + Body ++ Response 404 + + **Send if:** The specified module was not found. + + + Body + + + Response 422 **Send if:** The given item cannot be processed (e.g. if it is invalid). @@ -65,6 +172,45 @@ -### next operation -## next section -# next group +### Delete Module [DELETE /modules/{moduleId}] + +**Functionality:** Deletes the specified module. + +**Security:** Requires an authenticated user with the role `admin`. + + ++ Parameters + + moduleId: `3234` (required, number) - The ID of the module. + + ++ 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 404 + + **Send if:** The specified module was not found. + + + Body + + ++ Response 422 + + **Send if:** The given item cannot be processed (e.g. if it is invalid). + + + Body diff --git a/api-documentation/routes/orders.md b/api-documentation/routes/orders.md new file mode 100644 index 0000000..9606f36 --- /dev/null +++ b/api-documentation/routes/orders.md @@ -0,0 +1,163 @@ +# Group Orders + + + + +## Multiple Orders [/orders] + + + +### Retrieve Orders [GET /orders{?page,limit,userId,status,orderBy}] + +**Functionality:** Retrieves all orders that are visible to the current user (that is, only the orders of the logged in user or all orders if the logged in user as the role `admin`). + +**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`. + + userId: `1987` (optional, number) - A comma-separated list of user IDs to filter for. This property does not have any functionality if the current user does not have the role `admin`. + + 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 + + + + +## Specific Order [/orders/{orderId}] + ++ Parameters + + orderId: `5862` (required, number) - The ID of the order. + + + +### Modify Order [PATCH /orders/{orderId}] + +**Functionality:** Changes the given properties of the specified order. + +**Security:** Requires an authenticated user with the role `admin`. + + ++ Parameters + + orderId: `5862` (required, number) - The ID of the order. + + ++ Request (application/json) + + Attributes + + order (required) + + status: `OD` (optional, enum[string]) + + `PD` Pending + + `OD` Ordered + + `RJ` Rejected + + `AR` Arrived + + hint: `Enough books available.` (optional, string) + + ++ Response 200 (application/json; charset=utf-8) + + + Attributes + + order (required, order) + + + 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 404 + + **Send if:** The specified order was not found. + + + Body + + ++ Response 422 + + **Send if:** The given item cannot be processed (e.g. if it is invalid). + + + Body + + + +### Delete Order [DELETE /orders/{orderId}] + +**Functionality:** Deletes the specified order. + +**Security:** Requires an authenticated user with the role `admin` or the user who has created the order. + + ++ Parameters + + orderId: `5862` (required, number) - The ID of the order. + + ++ 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 404 + + **Send if:** The specified order was not found. + + + Body diff --git a/api-documentation/routes/routes.md b/api-documentation/routes/routes.md index 620579f..fc32ce1 100644 --- a/api-documentation/routes/routes.md +++ b/api-documentation/routes/routes.md @@ -1 +1,4 @@ + + + From b31a07b89ed2713740518e77c6d57e821e967654 Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Wed, 25 Jan 2017 14:38:51 +0100 Subject: [PATCH 5/8] Added README for the REST API documentation. --- api-documentation/README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 api-documentation/README.md diff --git a/api-documentation/README.md b/api-documentation/README.md new file mode 100644 index 0000000..a0840ac --- /dev/null +++ b/api-documentation/README.md @@ -0,0 +1,25 @@ +# REST API Documentation + +The REST API documentation is written in [API Blueprint][2] using [Aglio][1] for rendering the documentation into HTML. + + +## Aglio: Setup + +Setting up [Aglio][1] is pretty easy, you just have to install [NodeJS][3]/[NPM][4] and then run `npm install -g aglio`. + + +## 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. + + +## Aglio: Compiling before Pushing + +Please compile the documentation before pushing your changes using `aglio -i api-documentation.md -o api-documentation.html`. + + + +[1]: https://github.com/danielgtaylor/aglio +[2]: https://apiblueprint.org +[3]: https://nodejs.org +[4]: https://www.npmjs.com From 5906e2af03e15f1f9b80eae72fd57c4b52a9d629 Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Wed, 25 Jan 2017 14:42:37 +0100 Subject: [PATCH 6/8] Updated README. --- api-documentation/README.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/api-documentation/README.md b/api-documentation/README.md index a0840ac..3574e7a 100644 --- a/api-documentation/README.md +++ b/api-documentation/README.md @@ -3,23 +3,32 @@ The REST API documentation is written in [API Blueprint][2] using [Aglio][1] for rendering the documentation into HTML. -## Aglio: Setup +## Setup Setting up [Aglio][1] is pretty easy, you just have to install [NodeJS][3]/[NPM][4] and then run `npm install -g aglio`. -## Aglio: Development +## 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. -## Aglio: Compiling before Pushing +## 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 From 9cccafdf64d98fbf941aa57bc83c5522bac5bcc2 Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Wed, 25 Jan 2017 15:26:47 +0100 Subject: [PATCH 7/8] Fixed enum[string] member values. --- .../datastructures/datastructures.md | 23 +++++++++++-------- api-documentation/routes/books.md | 18 ++++++++------- api-documentation/routes/orders.md | 18 ++++++++------- 3 files changed, 33 insertions(+), 26 deletions(-) diff --git a/api-documentation/datastructures/datastructures.md b/api-documentation/datastructures/datastructures.md index 9f71293..a32fcb1 100644 --- a/api-documentation/datastructures/datastructures.md +++ b/api-documentation/datastructures/datastructures.md @@ -13,20 +13,22 @@ + 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. - + `AC` Accepted - + `RJ` Rejected - + `PP` Proposed - + `OL` Obsolete + + 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. - + `PD` Pending - + `OD` Ordered - + `RJ` Rejected - + `AR` Arrived + + 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. @@ -49,8 +51,9 @@ ## season (object) + id: `2156` (required, number) - The ID of the season. + season: `W` (required, enum[string]) - The season. - + `W` Winter term - + `S` Summer term + + Members + + `W` - Winter term + + `S` - Summer term + year: `2017` (required, string) - The year of the season. ## timeframe (object) diff --git a/api-documentation/routes/books.md b/api-documentation/routes/books.md index d42b038..126e0bd 100644 --- a/api-documentation/routes/books.md +++ b/api-documentation/routes/books.md @@ -18,10 +18,11 @@ + isbn: `9783836218023` (optional, isbn) - A comma-separated list of ISBNs to filter for. + title: `java` (optional, string) - The title to filter for. Represents a case-insensitive text search. + state: `AC` (optional, enum[string]) - A comma-separated list of states to filter for. - + `AC` Accepted - + `RJ` Rejected - + `PP` Proposed - + `OL` Obsolete + + Members + + `AC` - Accepted + + `RJ` - Rejected + + `PP` - Proposed + + `OL` - Obsolete + author: `ullenboom` (optional, string) - The author to filter for. Represents a case-insensitive text search. + orderBy: `author` (optional, enum[string]) - The field to order by. Defaults to no specific order. + `isbn` Order by the ISBN. @@ -172,10 +173,11 @@ + isbn: `9783836218023` (optional, isbn) + title: `Java ist auch eine Insel` (optional, string) + state: `AC` (optional, enum[string]) - + `AC` Accepted - + `RJ` Rejected - + `PP` Proposed - + `OL` Obsolete + + Members + + `AC` - Accepted + + `RJ` - Rejected + + `PP` - Proposed + + `OL` - Obsolete + author: `Christian Ullenboom` (optional, string) + price: `49.90` (optional, number) diff --git a/api-documentation/routes/orders.md b/api-documentation/routes/orders.md index 9606f36..58fe342 100644 --- a/api-documentation/routes/orders.md +++ b/api-documentation/routes/orders.md @@ -19,10 +19,11 @@ + limit: `10` (optional, number) - pagination - The number of items per page. Defaults to `10`. + userId: `1987` (optional, number) - A comma-separated list of user IDs to filter for. This property does not have any functionality if the current user does not have the role `admin`. + status: `OD` (optional, enum[string]) - A comma-separated list of states to filter for. - + `PD` Pending - + `OD` Ordered - + `RJ` Rejected - + `AR` Arrived + + Members + + `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. @@ -82,10 +83,11 @@ + Attributes + order (required) + status: `OD` (optional, enum[string]) - + `PD` Pending - + `OD` Ordered - + `RJ` Rejected - + `AR` Arrived + + Members + + `PD` - Pending + + `OD` - Ordered + + `RJ` - Rejected + + `AR` - Arrived + hint: `Enough books available.` (optional, string) From ec34ab6cbb93dc3f9b94e6968b6caf4a3739417e Mon Sep 17 00:00:00 2001 From: Fabian Damken Date: Wed, 25 Jan 2017 15:27:59 +0100 Subject: [PATCH 8/8] Rendered documentation. --- api-documentation/api-documentation.html | 118 +++++++++-------------- 1 file changed, 45 insertions(+), 73 deletions(-) diff --git a/api-documentation/api-documentation.html b/api-documentation/api-documentation.html index e81f959..7ce7f4e 100644 --- a/api-documentation/api-documentation.html +++ b/api-documentation/api-documentation.html @@ -439,21 +439,7 @@

Example URI

GET&
isbn
isbn (optional) Example: 9783836218023

A comma-separated list of ISBNs to filter for.

title
string (optional) Example: java

The title to filter for. Represents a case-insensitive text search.

state
string (optional) Example: AC

A comma-separated list of states to filter for.

-
    -
  • -

    AC Accepted

    -
    • -
  • -

    RJ Rejected

    -
    • -
  • -

    PP Proposed

    -
    • -
  • -

    OL Obsolete

    -
    • -
-
author
string (optional) Example: ullenboom

The author to filter for. Represents a case-insensitive text search.

+

Choices: AC RJ PP OL

author
string (optional) Example: ullenboom

The author to filter for. Represents a case-insensitive text search.

orderBy
string (optional) Example: author

The field to order by. Defaults to no specific order.

  • @@ -575,10 +561,10 @@

    Example URI

    PUT& "state": { "type": "string", "enum": [ - "`AC` Accepted", - "`RJ` Rejected", - "`PP` Proposed", - "`OL` Obsolete" + "AC", + "RJ", + "PP", + "OL" ], "description": "secured - The state of the book." }, @@ -634,10 +620,10 @@

    Example URI

    PUT& "state": { "type": "string", "enum": [ - "`AC` Accepted", - "`RJ` Rejected", - "`PP` Proposed", - "`OL` Obsolete" + "AC", + "RJ", + "PP", + "OL" ], "description": "secured - The state of the book." }, @@ -699,10 +685,10 @@

    Example URI

    GET& "state": { "type": "string", "enum": [ - "`AC` Accepted", - "`RJ` Rejected", - "`PP` Proposed", - "`OL` Obsolete" + "AC", + "RJ", + "PP", + "OL" ], "description": "secured - The state of the book." }, @@ -749,10 +735,10 @@

    Example URI

    PATCHstate": { "type": "string", "enum": [ - "`AC` Accepted", - "`RJ` Rejected", - "`PP` Proposed", - "`OL` Obsolete" + "AC", + "RJ", + "PP", + "OL" ] }, "author": { @@ -793,10 +779,10 @@

    Example URI

    PATCHstate": { "type": "string", "enum": [ - "`AC` Accepted", - "`RJ` Rejected", - "`PP` Proposed", - "`OL` Obsolete" + "AC", + "RJ", + "PP", + "OL" ], "description": "secured - The state of the book." }, @@ -902,8 +888,8 @@

    Example URI

    PUT& "season": { "type": "string", "enum": [ - "`W` Winter term", - "`S` Summer term" + "W", + "S" ], "description": "The season." }, @@ -983,8 +969,8 @@

    Example URI

    PUT& "season": { "type": "string", "enum": [ - "`W` Winter term", - "`S` Summer term" + "W", + "S" ], "description": "The season." }, @@ -1072,8 +1058,8 @@

    Example URI

    GET& "season": { "type": "string", "enum": [ - "`W` Winter term", - "`S` Summer term" + "W", + "S" ], "description": "The season." }, @@ -1144,8 +1130,8 @@

    Example URI

    PATCHseason": { "type": "string", "enum": [ - "`W` Winter term", - "`S` Summer term" + "W", + "S" ], "description": "The season." }, @@ -1220,8 +1206,8 @@

    Example URI

    PATCHseason": { "type": "string", "enum": [ - "`W` Winter term", - "`S` Summer term" + "W", + "S" ], "description": "The season." }, @@ -1271,21 +1257,7 @@

    Example URI

    GET&
limit
number (optional) Example: 10

pagination - The number of items per page. Defaults to 10.

userId
number (optional) Example: 1987

A comma-separated list of user IDs to filter for. This property does not have any functionality if the current user does not have the role admin.

status
string (optional) Example: OD

A comma-separated list of states to filter for.

-
    -
  • -

    PD Pending

    -
    • -
  • -

    OD Ordered

    -
    • -
  • -

    RJ Rejected

    -
    • -
  • -

    AR Arrived

    -
    • -
-
orderBy
string (optional) Example: status

The field to order by. Defaults to no specific order.

+

Choices: PD OD RJ AR

orderBy
string (optional) Example: status

The field to order by. Defaults to no specific order.

  • status Order by the status.

    @@ -1341,7 +1313,7 @@

    Example URI

    GET&

    Example URI

    PATCH https://www.d120.de/studierende/buchaktion/api/orders/5862
    URI Parameters
    HideShow
    orderId
    number (required) Example: 5862

    The ID of the order.

    Request
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
   "order": {
-    "status": "`PD` Pending",
+    "status": "PD",
     "hint": "Enough books available."
   }
 }
    Schema
    {
@@ -1354,10 +1326,10 @@ 
    Example URI
    PATCHstatus": {
           "type": "string",
           "enum": [
-            "`PD` Pending",
-            "`OD` Ordered",
-            "`RJ` Rejected",
-            "`AR` Arrived"
+            "PD",
+            "OD",
+            "RJ",
+            "AR"
           ]
         },
         "hint": {
@@ -1404,10 +1376,10 @@ 
    Example URI
    PATCHstatus": {
           "type": "string",
           "enum": [
-            "`PD` Pending",
-            "`OD` Ordered",
-            "`RJ` Rejected",
-            "`AR` Arrived"
+            "PD",
+            "OD",
+            "RJ",
+            "AR"
           ],
           "description": "semi-secured - The status of the order."
         },
@@ -1433,10 +1405,10 @@ 
    Example URI
    PATCHstate": {
               "type": "string",
               "enum": [
-                "`AC` Accepted",
-                "`RJ` Rejected",
-                "`PP` Proposed",
-                "`OL` Obsolete"
+                "AC",
+                "RJ",
+                "PP",
+                "OL"
               ],
               "description": "secured - The state of the book."
             },