FAQ | This is a LIVE service | Changelog

Commit 5f5407f6 authored by Dean Rasheed's avatar Dean Rasheed
Browse files

Documentation update re. privileges.

For API methods that require authentication, be more explicit about the
exact privileges required.

Additionally, in the PHP docs, increased the spacing above the HTTP
method and path that is automatically inserted at the bottom of each
method's docs.
parent 198dba12
......@@ -120,6 +120,20 @@
* By default, only a few basic details about the booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* Note that viewing bookings requires authentication, and a booking is
* only visible to the following:
* <ul>
* <li>The participant.</li>
* <li>The person who made the booking (not necessarily the
* participant).</li>
* <li>The event's trainers.</li>
* <li>The event's administrator, owner and booker.</li>
* <li>People with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>People with the "view-3rd-party-booking" privilege for the event's
* provider.</li>
* </ul>
*
* @param id [required] The ID of the booking to fetch.
* @param fetch [optional] A comma-separated list of any additional
......@@ -154,6 +168,17 @@
* whether or not the participant attended, or it may be set to
* {@code null} (its original value) to indicate that their attendance
* has not yet been recorded, or is currently unknown.
* <p>
* Note that updating attendance requires authentication as a user with
* permission to view the booking (see
* {@link #getBooking(Long,String) getBooking()}) and record attendance
* on the event. So in addition to being able to view the booking, the
* user must be either one of the following:
* <ul>
* <li>The event administrator.</li>
* <li>A person with the "record-attendance" privilege for the event's
* provider.</li>
* </ul>
*
* @param id [required] The ID of the booking to update.
* @param sessionNumber [optional] The session to update the attendance
......@@ -501,6 +526,17 @@
* NOTE: This will return <b>all</b> bookings, including cancelled
* bookings. Check each booking's {@link UTBSEventBooking#status status}
* field to see which are confirmed bookings.
* <p>
* Note that viewing an event's bookings requires authentication as one
* of the following:
* <ul>
* <li>One of the event's trainers.</li>
* <li>The event's administrator, owner or booker.</li>
* <li>A person with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>A person with the "view-3rd-party-booking" privilege for the
* event's provider.</li>
* </ul>
*
* @param id [required] The ID of the event.
* @param fetch [optional] A comma-separated list of any additional
......@@ -532,6 +568,11 @@
* they do not already have one. If a booking is created in this way, its
* status will be "did not book", to indicate that the participant did
* not book onto the event themselves.
* <p>
* Note that this requires authentication as a user with permission to
* view the event's bookings and record attendance on the event.
* Additionally, the "create-3rd-party-booking" privilege is required if
* {@code autoCreateBooking} is set.
*
* @param id [required] The ID of the event.
* @param sessionNumber [required] The session to record attendance for.
......@@ -629,6 +670,13 @@
<doc>
/**
* Get the person with the specified CRSid.
* &lt;p&gt;
* Note that viewing people requires authentication, and a person's
* details are only visible to the following:
* &lt;ul&gt;
* &lt;li&gt;The person themselves.&lt;/li&gt;
* &lt;li&gt;People with the "view-person-details" privilege.&lt;/li&gt;
* &lt;/ul&gt;
*
* @param crsid [required] The CRSid of the person to fetch.
* @param fetch [optional] A comma-separated list of any additional
......@@ -662,6 +710,12 @@
* By default, only a few basic details about each booking are returned,
* but the optional &lt;code&gt;fetch&lt;/code&gt; parameter may be used to fetch
* additional details about each booking.
* &lt;p&gt;
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* @param crsid [required] The CRSid of the person.
* @param fetch [optional] A comma-separated list of any additional
......@@ -693,6 +747,12 @@
* By default, only a few basic details about each booking are returned,
* but the optional &lt;code&gt;fetch&lt;/code&gt; parameter may be used to fetch
* additional details about each booking.
* &lt;p&gt;
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* @param crsid [required] The CRSid of the person.
* @param fetch [optional] A comma-separated list of any additional
......@@ -730,6 +790,12 @@
* By default, only a few basic details about each booking are returned,
* but the optional &lt;code&gt;fetch&lt;/code&gt; parameter may be used to fetch
* additional details about each booking.
* &lt;p&gt;
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* @param crsid [required] The CRSid of the person.
* @param fetch [optional] A comma-separated list of any additional
......
......@@ -1040,6 +1040,11 @@ def javadocs_to_phpdocs(docs, line_prefix=""):
# Replace <b>XXX</b> with **XXX**
docs = re.sub("(?s)<b>(.+?)</b>", "**\\1**", docs)
# Ugly method of adding a little extra vertical space before the HTTP
# method and path we added (only about half a line's height)
docs = re.sub("<code style=\"[^\"]+\">(\\[ HTTP: [^\\]]* \\])</code>",
"`` ``\n<p>\n``\\1``", docs)
# Replace single-line <code>XXX</code> blocks with ``XXX``
docs = re.sub("<code[^>]*>(.+?)</code>", "``\\1``", docs)
......
......@@ -89,6 +89,20 @@ public class BookingMethods
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* Note that viewing bookings requires authentication, and a booking is
* only visible to the following:
* <ul>
* <li>The participant.</li>
* <li>The person who made the booking (not necessarily the
* participant).</li>
* <li>The event's trainers.</li>
* <li>The event's administrator, owner and booker.</li>
* <li>People with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>People with the "view-3rd-party-booking" privilege for the event's
* provider.</li>
* </ul>
* <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/booking/{id} ]</code>
*
* @param id [required] The ID of the booking to fetch.
......@@ -127,6 +141,17 @@ public class BookingMethods
* {@code null} (its original value) to indicate that their attendance
* has not yet been recorded, or is currently unknown.
* <p>
* Note that updating attendance requires authentication as a user with
* permission to view the booking (see
* {@link #getBooking(Long,String) getBooking()}) and record attendance
* on the event. So in addition to being able to view the booking, the
* user must be either one of the following:
* <ul>
* <li>The event administrator.</li>
* <li>A person with the "record-attendance" privilege for the event's
* provider.</li>
* </ul>
* <p>
* <code style="background-color: #eec;">[ HTTP: PUT /api/v1/booking/{id}/attendance ]</code>
*
* @param id [required] The ID of the booking to update.
......
......@@ -217,6 +217,17 @@ public class EventMethods
* bookings. Check each booking's {@link UTBSEventBooking#status status}
* field to see which are confirmed bookings.
* <p>
* Note that viewing an event's bookings requires authentication as one
* of the following:
* <ul>
* <li>One of the event's trainers.</li>
* <li>The event's administrator, owner or booker.</li>
* <li>A person with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>A person with the "view-3rd-party-booking" privilege for the
* event's provider.</li>
* </ul>
* <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/event/{id}/bookings ]</code>
*
* @param id [required] The ID of the event.
......@@ -251,6 +262,11 @@ public class EventMethods
* status will be "did not book", to indicate that the participant did
* not book onto the event themselves.
* <p>
* Note that this requires authentication as a user with permission to
* view the event's bookings and record attendance on the event.
* Additionally, the "create-3rd-party-booking" privilege is required if
* {@code autoCreateBooking} is set.
* <p>
* <code style="background-color: #eec;">[ HTTP: PUT /api/v1/event/{id}/{sessionNumber}/attendance ]</code>
*
* @param id [required] The ID of the event.
......
......@@ -53,6 +53,13 @@ public class PersonMethods
/**
* Get the person with the specified CRSid.
* <p>
* Note that viewing people requires authentication, and a person's
* details are only visible to the following:
* <ul>
* <li>The person themselves.</li>
* <li>People with the "view-person-details" privilege.</li>
* </ul>
* <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/person/{crsid} ]</code>
*
* @param crsid [required] The CRSid of the person to fetch.
......@@ -90,6 +97,12 @@ public class PersonMethods
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
* <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/person/{crsid}/current-bookings ]</code>
*
* @param crsid [required] The CRSid of the person.
......@@ -125,6 +138,12 @@ public class PersonMethods
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
* <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/person/{crsid}/interested-bookings ]</code>
*
* @param crsid [required] The CRSid of the person.
......@@ -166,6 +185,12 @@ public class PersonMethods
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
* <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/person/{crsid}/training-history ]</code>
*
* @param crsid [required] The CRSid of the person.
......
......@@ -86,6 +86,26 @@ class BookingMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references.
*
* Note that viewing bookings requires authentication, and a booking is
* only visible to the following:
*
* * The participant.
*
* * The person who made the booking (not necessarily the
* participant).
*
* * The event's trainers.
*
* * The event's administrator, owner and booker.
*
* * People with the "view-event-bookings" privilege for the event's
* provider.
*
* * People with the "view-3rd-party-booking" privilege for the event's
* provider.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/booking/{id} ]``
*
* @param int $id [required] The ID of the booking to fetch.
......@@ -123,6 +143,19 @@ class BookingMethods
* ``null`` (its original value) to indicate that their attendance
* has not yet been recorded, or is currently unknown.
*
* Note that updating attendance requires authentication as a user with
* permission to view the booking (see
* {@link getBooking()}) and record attendance
* on the event. So in addition to being able to view the booking, the
* user must be either one of the following:
*
* * The event administrator.
*
* * A person with the "record-attendance" privilege for the event's
* provider.
*
* `` ``
*
* ``[ HTTP: PUT /api/v1/booking/{id}/attendance ]``
*
* @param int $id [required] The ID of the booking to update.
......
......@@ -83,6 +83,8 @@ class CourseMethods
* The ``fetch`` parameter may also be used to fetch the themes
* that contain the course.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/course/{id} ]``
*
* @param string $id [required] The ID of the course to fetch.
......@@ -134,6 +136,8 @@ class CourseMethods
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/course/{id}/events-in-time-period ]``
*
* @param string $id [required] The ID of the course.
......@@ -178,6 +182,8 @@ class CourseMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/course/{id}/self-taught-events ]``
*
* @param string $id [required] The ID of the course.
......
......@@ -142,6 +142,8 @@ class EventMethods
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/event/events-in-time-period ]``
*
* @param DateTime $start [optional] The start of the time period to search. If
......@@ -184,6 +186,8 @@ class EventMethods
* the optional ``fetch`` parameter may be used to fetch
* additional details.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/event/{id} ]``
*
* @param int $id [required] The ID of the event to fetch.
......@@ -219,6 +223,21 @@ class EventMethods
* bookings. Check each booking's {@link status}
* field to see which are confirmed bookings.
*
* Note that viewing an event's bookings requires authentication as one
* of the following:
*
* * One of the event's trainers.
*
* * The event's administrator, owner or booker.
*
* * A person with the "view-event-bookings" privilege for the event's
* provider.
*
* * A person with the "view-3rd-party-booking" privilege for the
* event's provider.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/event/{id}/bookings ]``
*
* @param int $id [required] The ID of the event.
......@@ -252,6 +271,13 @@ class EventMethods
* status will be "did not book", to indicate that the participant did
* not book onto the event themselves.
*
* Note that this requires authentication as a user with permission to
* view the event's bookings and record attendance on the event.
* Additionally, the "create-3rd-party-booking" privilege is required if
* ``autoCreateBooking`` is set.
*
* `` ``
*
* ``[ HTTP: PUT /api/v1/event/{id}/{sessionNumber}/attendance ]``
*
* @param int $id [required] The ID of the event.
......
......@@ -73,6 +73,8 @@ class InstitutionMethods
* returned, but the optional ``fetch`` parameter may be used to
* fetch additional details.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/institution/{instid} ]``
*
* @param string $instid [required] The ID of the institution to fetch.
......
......@@ -46,6 +46,15 @@ class PersonMethods
/**
* Get the person with the specified CRSid.
*
* Note that viewing people requires authentication, and a person's
* details are only visible to the following:
*
* * The person themselves.
*
* * People with the "view-person-details" privilege.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/person/{crsid} ]``
*
* @param string $crsid [required] The CRSid of the person to fetch.
......@@ -82,6 +91,14 @@ class PersonMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional details about each booking.
*
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/person/{crsid}/current-bookings ]``
*
* @param string $crsid [required] The CRSid of the person.
......@@ -116,6 +133,14 @@ class PersonMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional details about each booking.
*
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/person/{crsid}/interested-bookings ]``
*
* @param string $crsid [required] The CRSid of the person.
......@@ -156,6 +181,14 @@ class PersonMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional details about each booking.
*
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/person/{crsid}/training-history ]``
*
* @param string $crsid [required] The CRSid of the person.
......
......@@ -84,6 +84,8 @@ class ProgrammeMethods
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/programme/programmes-by-date ]``
*
* @param DateTime $startDate [optional] The start date. If omitted, this will
......@@ -121,6 +123,8 @@ class ProgrammeMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional details.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/programme/{id} ]``
*
* @param int $id [required] The ID of the programme to fetch.
......@@ -172,6 +176,8 @@ class ProgrammeMethods
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/programme/{id}/events-in-time-period ]``
*
* @param int $id [required] The ID of the programme.
......@@ -216,6 +222,8 @@ class ProgrammeMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/programme/{id}/self-taught-events ]``
*
* @param int $id [required] The ID of the programme.
......
......@@ -84,6 +84,8 @@ class ProviderMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/provider/all-providers ]``
*
* @param string $fetch [optional] A comma-separated list of any additional
......@@ -113,6 +115,8 @@ class ProviderMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/provider/{shortName} ]``
*
* @param string $shortName [required] The short name of the provider to fetch.
......@@ -165,6 +169,8 @@ class ProviderMethods
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/provider/{shortName}/events-in-time-period ]``
*
* @param string $shortName [required] The short name of the provider.
......@@ -209,6 +215,8 @@ class ProviderMethods
* returned, but the optional ``fetch`` parameter may be used to
* fetch additional attributes or references of each programme.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/provider/{shortName}/programmes ]``
*
* @param string $shortName [required] The short name of the provider.
......@@ -251,6 +259,8 @@ class ProviderMethods
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/provider/{shortName}/programmes-by-date ]``
*
* @param string $shortName [required] The short name of the provider.
......@@ -290,6 +300,8 @@ class ProviderMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references of each programme.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/provider/{shortName}/themes ]``
*
* @param string $shortName [required] The short name of the provider.
......@@ -321,6 +333,8 @@ class ProviderMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references of each programme.
*
* `` ``
*
* ``[ HTTP: GET /api/v1/provider/{shortName}/venues ]``
*
* @param string $shortName [required] The short name of the provider.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment