Description of the RESTful API used in ATB 2.0

Resources

ACL Contact Entries

Resource Description
GET /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/contacts List of ACL contact entries
GET /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/contacts/:id Show an ACL contact entry
POST /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/contacts Create a ACL contact entry
PATCH /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/contacts/:id Update an ACL contact
PUT /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/contacts/:id Update an ACL contact
DELETE /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/contacts/:id Destroy (revoke access for) an ACL contact
DELETE /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/forfeit User can forfeit (revoke access for) their own contact access

ACL Group Entries

Resource Description
GET /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/groups List of ACL group entries
GET /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/groups/:id Show an ACL group entry
POST /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/groups Create a ACL group entry
PATCH /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/groups/:id Update an ACL group entry
PUT /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/groups/:id Update an ACL group entry
DELETE /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/groups/:id Destroy (revoke access for) an ACL group
GET /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/groups/:id/contacts List of contacts belonging to a group

ACL Pending User Entries

Resource Description
GET /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/pending_users List of pending book access requests
GET /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/pending_users/:id Show an annotation set access request
POST /portal/api/books/:book_id/annotation_sets/:annotation_set_id/request_access Create an annotation set access request
POST /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/pending_users Create an annotation set access request
PATCH /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/pending_users/:id Update (approve) an annotation set access request
PUT /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/pending_users/:id Update (approve) an annotation set access request
DELETE /portal/api/books/:book_id/annotation_sets/:annotation_set_id/acl_entries/pending_users/:id Destroy (deny) an annotation set access request

Active textbooks

Resource Description
GET /books/:id Load and show specified book within the ATB viewing/authoring tool
GET /books/:id Load and show specified book within the ATB viewing/authoring tool
GET /books/:active_textbook_id/annotation_sets/:annotation_set_id Load and show specified book within the ATB viewing/authoring tool
GET /active_textbooks/:active_textbook_id/annotation_sets/:annotation_set_id Load and show specified book within the ATB viewing/authoring tool
GET /active_textbooks/:id Load and show specified book within the ATB viewing/authoring tool
POST /active_textbooks/:active_textbook_id(/annotation_sets/:annotation_set_id) Load and show specified book within the ATB viewing/authoring tool

Annotation sets

Resource Description
GET /portal/api/books/:book_id/annotation_sets List of annotation sets that belong to a book
GET /portal/api/books/:book_id/annotation_sets/:id Show an annotation set
PATCH /portal/api/books/:book_id/annotation_sets/:id Update an annotation set
PUT /portal/api/books/:book_id/annotation_sets/:id Update an annotation set
POST /portal/api/books/:book_id/annotation_sets Create an annotation set
DELETE /portal/api/books/:book_id/annotation_sets/:id Destroy an annotation set
GET /portal/api/current_user/annotation_sets/:id/quizzes List current user's quizzes for an annotation set
GET /portal/api/current_user/annotation_sets/:id/comments List current user's comments for an annotation set

Book categories

Resource Description
GET /portal/api/book_categories List of all book categories
GET /portal/api/book_categories/entire_tree Show entire book categories tree
GET /portal/api/book_categories/:id Show a book category
GET /portal/api/book_categories/:id/show_with_children Show a book category and all child categories
GET /portal/api/book_categories/:id/show_with_parents Show a book category and all parent categories
POST /portal/api/book_categories Create a new book category
PATCH /portal/api/book_categories/:id Update a book category
PUT /portal/api/book_categories/:id Update a book category
DELETE /portal/api/book_categories/:id Destroy a book category
GET /portal/api/book_categories/:id/thumbnail Show a thumbnail for a book category

Books

Resource Description
GET /portal/api/books/authored List of books
GET /portal/api/books List of books
GET /portal/api/books/:id Show a book
POST /portal/api/books Create a book
PATCH /portal/api/books/:id Update a book
PUT /portal/api/books/:id Update a book
DELETE /portal/api/books/:id Destroy a book

Contacts

Resource Description
GET /portal/api/current_user/contacts List of contacts that belong to the current user
GET /portal/api/current_user/contacts/:id Show a contact
POST /portal/api/current_user/contacts Create a contact
PATCH /portal/api/current_user/contacts/:id Update a contact
PUT /portal/api/current_user/contacts/:id Update a contact
DELETE /portal/api/current_user/contacts/:id Destroy a contract
GET /portal/api/current_user/contacts/:id/groups List of all groups owned the current user

Current user

Resource Description
PUT /portal/api/current_user Update the current user
GET /portal/api/current_user Show the current user

Devices

Resource Description
GET /api/devices List of devices that are registered
GET /api/devices/:id Show a device that is registered
POST /api/devices Create a registered device
DELETE /api/devices/:id Destroy a registered device

Document migrations

Resource Description
POST /api/admin/document_migrations/restore Restore an ATB from an MATB file
GET /api/admin/document_migrations/download Download a MATB file for an ATB.

Eula

Resource Description
GET /eula Show the EULA
POST /eula Accept EULA for current user

Group requests

Resource Description
GET /portal/api/current_user/group_requests List of group access requests that belong to the current user
POST /portal/api/current_user/group_requests Create a group access request for the current user
GET /portal/api/current_user/group_requests/:id Show a group access request
PATCH /portal/api/current_user/group_requests/:id Update (approve) a group access request
PUT /portal/api/current_user/group_requests/:id Update (approve) a group access request
DELETE /portal/api/current_user/group_requests/:id Destroy (reject) a group access request

Groups

Resource Description
GET /portal/api/current_user/groups List of groups that the current user belongs to
GET /portal/api/current_user/groups/:id Show a group
POST /portal/api/current_user/groups Create a group
PATCH /portal/api/current_user/groups/:id Update a group
PUT /portal/api/current_user/groups/:id Update a group
GET /portal/api/current_user/groups/:id/books List of books that belong to a group
GET /portal/api/current_user/groups/:id/contacts List of contacts that belong to a group
POST /portal/api/current_user/groups/:id/add_contact Add a contact to a group
DELETE /portal/api/current_user/groups/:id/remove_contact Remove a contact from a group
POST /portal/api/current_user/groups/:id/join Join a group
DELETE /portal/api/current_user/groups/:id Destroy a group
DELETE /portal/api/current_user/groups/:id/leave Leave a group

Notifications

Resource Description
GET /portal/api/current_user/notifications List of notifications that belong to the current user
GET /portal/api/current_user/notifications/:id Show a notification
PATCH /portal/api/current_user/notifications/:id Update a notification as read/unread
PUT /portal/api/current_user/notifications/:id Update a notification as read/unread
DELETE /portal/api/current_user/notifications/:id Destroy a notification
DELETE /portal/api/current_user/notifications Destroy all notifications that belong to the current user

Offline downloads

Resource Description
POST /api/active_textbooks/:active_textbook_id/offline_downloads(/annotation_sets/:annotation_set_id)/prepare Prepare an offline download
GET /api/active_textbooks/:active_textbook_id/offline_downloads/status Show the status of an offline download
GET /api/active_textbooks/:active_textbook_id/offline_downloads/properties Show the properties of an offline download
GET /api/active_textbooks/:active_textbook_id/offline_downloads(/annotation_sets/:annotation_set_id)/fetch/:type Begin an offline download

Offline sync

Resource Description
POST /api/active_textbooks/:active_textbook_id/annotation_sets/:annotation_set_id/offline_sync Sync with native clients

Orders

Resource Description
GET /portal/api/orders List of orders made by the current user
GET /portal/api/orders/:id Show an order

Password resets

Resource Description
POST /password_resets/reset Reset Password

Reports

Resource Description
GET /portal/api/current_user/reports List of reports
GET /portal/api/current_user/reports/:id Show a report
GET /portal/api/current_user/reports/download Download report consisting of multiple annotation sets
GET /portal/api/current_user/reports/read_document_report Export Read Documents report
GET /portal/api/current_user/reports/book_study_progress_info Export Book Study progress info report
GET /portal/api/current_user/reports/test_info Export Test Info report
GET /portal/api/current_user/reports/answer_info Export Answer Info report

Sessions

Resource Description
POST /sessions Login a user
POST /login Login a user
DELETE /sessions/:id Log the current user out
GET /logout Log the current user out

Urms

Resource Description
POST /api/urms/auth_token Generate URMS device auth token
GET /api/urms/enabled Query if server supports URMS DRM

Usages

Resource Description
GET /portal/api/usage Usage statistics for a book

User confirmations

Resource Description
POST /user_confirmations/confirm_email_address Confirm email address for given user

User signup invitations

Resource Description
GET /portal/api/current_user/user_signup_invitations List of user invitations
GET /portal/api/current_user/user_signup_invitations/:id Show a user invitation
POST /portal/api/current_user/user_signup_invitations Create a user signup invitation
DELETE /portal/api/current_user/user_signup_invitations/:id Destroy a user invitation

Users

Resource Description
POST /signup Create a new user
POST /users Create a new user
PATCH /users/:id Update a user
PUT /users/:id Update a user
GET /users List of users
GET /users/:id Show a user. Admins can show any user, normal users can only get their own details.