Note: all fields within urls need to be encoded (for example, every space needs to be replaced with %20). Links given by the api will do this for you, so you only need to actively think about it when manually composing a URL.
For automatic clients, it's recommended to accept only json responses. All json responses come with a boolean success field, so it can easily be detected whether the operation was sucessful or not.
Useful links
There is no list of playback positions, since this is less useful to know, but there is a per-user list on every user page, and a per-book list on every audiobook page. Similarly, there is no general list of reviews, but a per-book list is present on every audiobook page.
Viewing resources
All of these can be viewed in either html or json by visiting the relevant page using a GET request. The fields may have slightly different names in json (for example, json field names will always be in lowercase), so every field name is described by the format <html-name> (<json-name>): <datatype>
/users/<username>
Description
Gives general information about the given user, as well as their listened books
List of fields
- Name (name): String
- E-mail (email): String
- Listened books (audiobooks): (list of the following)
Html
- Book: link to book
- Position: playback position in seconds
Json
- audiobook:
- title: String
- authors: [String]
- link: String
- position: Number (this is in milliseconds)
/audiobooks/<title>/<list>/<of>/<authors>
Description
Gives general information about the given audiobook, as well as all reviews on the book and all listens on the book
List of fields
- Title (title): String
- Authors (authors): [String]
- Genres (genres): (can be null or empty, list of the following)
- Description (description): String (can be null or absent)
- Publication date (publication): String (can be null) (if present, represents a date in dd/mm/yyyy)
- Link (link): String (can be null) (clickable in html)
- Duration (duration): Number (milliseconds in json, seconds in html)
- Average rating (rating): Number
- Reviews (reviews): (list of the following)
- User (user):
- Description (description): String (can be null or absent)
- Rating (rating): Number
- Listens (listens): (list of the following)
- User (user):
- Position (position): Number (milliseconds in json, seconds in html)
/genres/<name>
Description
Gives general information about the given genre, as well as all books in the genre
List of fields
- Name genre (name): String
- Description (description): String (can be null or absent)
- Audiobooks (audiobooks): (list of the following)
Json
- title: String
- authors: [String]
- link: String
/reviews/<username>/<audiobook_title>/<list>/<of>/<audiobook>/<authors>
Description
Gives general information about the given review
List of fields
- User (user):
- Audiobook (audiobook):
Json
- title: String
- authors: [String]
- link: String
- Description (description): String (can be null or absent)
- Rating (rating): Number
/playback_positions/<username>/<audiobook_title>/<list>/<of>/<audiobook>/<authors>
Description
Gives general information about the given playback position
List of fields
- User (user):
- Audiobook (audiobook):
Json
- title: String
- authors: [String]
- link: String
- Position (position): Number (milliseconds in json, seconds in html)
Adding resources
All of these can be done by sending a POST request containing the supplied data in json format. Some of these fields are optional and/or have specific validations, all of these are noted next to each field. Note: all of the examples have an echo appended to them, this does not do anything functionally but ensures the output will end with a newline so the cli layout still behaves normally.
/users/
Expected data
- name: String (required, needs to be non-empty)
- email: String (optional, needs to be non-empty)
Example
curl -H "Content-Type: application/json" -X POST https://groep04.webdev.stud.atlantis.UGent.be/users -d '{"name": "Bob", "email": "bob.bobszoon@gmail.com"}' && echo
/audiobooks/
Expected data
- title: String (required, needs to be non-empty)
- authors: [String] (required, needs to be non-empty, and all entries need to be non-empty)
- genres: [String] (optional, all entries need to refer to an existing genre)
- description: String (optional, needs to be non-empty if present)
- publication: String (optional, needs to be a valid date in dd/mm/yyyy if present)
- link: String (optional, needs to be a valid http(s) link if present)
- duration: Number (optional, needs to be strictly positive if present)
Example
curl -H "Content-Type: application/json" -X POST https://groep04.webdev.stud.atlantis.UGent.be/audiobooks -d '{"title": "Lord of the Rings: The Fellowship of the Ring", "authors": ["J.R.R. Tolkien"], "genres": ["Fantasy"], "description": "I don't remember the whole plot, but there are nine rings and one of them rules the others and it should have been thrown into the volcano of Mordor, the only thing hot enough to destroy it, thousands of years ago, but it wasn't, so now everyone is in trouble. This is the first book of the trilogy.", "publication": "29/07/1954", "link": "https://en.wikipedia.org/wiki/The_Fellowship_of_the_Ring", "duration": 100000000000000000}' && echo
/genres/
Expected data
- name: String (required, needs to be non-empty)
- description: String (optional, needs to be non-empty if present)
Example
curl -H "Content-Type: application/json" -X POST https://groep04.webdev.stud.atlantis.UGent.be/genres -d '{"name": "Fantasy", "description": "About things far away from reality, like wizards, unicorns, dragons, and not having to pay taxes."}' && echo
/reviews/
Expected data
- username: String (required, needs to refer to an existing user)
- audiobook_title: String (required, needs to refer to an existing audiobook)
- audiobook_authors: [String] (required, needs to refer to an existing audiobook)
- description: String (optional, needs to be non-empty if present)
- rating: Number (required, needs to be within the interval [0, 10])
Example
curl -H "Content-Type: application/json" -X POST https://groep04.webdev.stud.atlantis.UGent.be/reviews -d '{"username": "Bob", "audiobook_title": "Lord of the Rings: The Fellowship of the Ring", "audiobook_authors": ["J.R.R. Tolkien"], "description": "I stopped listening to this because it was too unrealistic. Frodo puts on the ring and turns invisible? That's not how any ring I've ever seen works.", "rating": 0}' && echo
/playback_positions/
Expected data
- username: String (required, needs to refer to an existing user)
- audiobook_title: String (required, needs to refer to an existing audiobook)
- audiobook_authors: [String] (required, needs to refer to an existing audiobook)
- position: Number (required, needs to be strictly positive and can't be longer than the audiobook duration if the audiobook has one)
Example
curl -H "Content-Type: application/json" -X POST https://groep04.webdev.stud.atlantis.UGent.be/reviews -d '{"username": "Bob", "audiobook_title": "Lord of the Rings: The Fellowship of the Ring", "audiobook_authors": ["J.R.R. Tolkien"], "position": "180000"}' && echo