From 7a1081a974a9cec6a59dda46f1c13d8096e54966 Mon Sep 17 00:00:00 2001 From: Paul Trudel Date: Wed, 8 May 2024 13:40:46 +0000 Subject: [PATCH] Update docs to accurately document API functionality --- docs/docs/development/api.md | 30 ++++++++++++++++-------------- docs/docs/new-features.md | 6 ------ 2 files changed, 16 insertions(+), 20 deletions(-) diff --git a/docs/docs/development/api.md b/docs/docs/development/api.md index b797b15718..492c914424 100644 --- a/docs/docs/development/api.md +++ b/docs/docs/development/api.md @@ -106,7 +106,7 @@ Updated in 2.7: - **create** - **Added:** `preUploadedPresentation`, `preUploadedPresentationName`, `disabledFeatures` options`cameraAsContent`, `snapshotOfCurrentSlide`, `downloadPresentationOriginalFile`, `downloadPresentationConvertedToPdf`, `timer`, `learningDashboardDownloadSessionData` (2.7.5). -- **join** - **Added:** `redirectErrorUrl`, `userdata-bbb_fullaudio_bridge` +- **join** - **Added:** `redirectErrorUrl`, `userdata-bbb_fullaudio_bridge` and removed support for all HTTP request methods except GET ## API Data Types @@ -211,6 +211,8 @@ To use the security model, you must be able to create a SHA-1 checksum out of th You **MUST** send this checksum with **EVERY** API call. Since end users do not know your shared secret, they can not fake calls to the server, and they can not modify any API calls since changing a single parameter name or value by only one character will completely change the checksum required to validate the call. +**NOTE** Checksums for POST requests must be calculated using the URL query string as well. For example, if all request parameters are in the request body then the checksum will be calculated using an empty query string. + Implementations of the SHA-1 functionality exist in nearly all programming languages. Here are example methods or links to example implementations for various languages: - [JavaScript](http://pajhome.org.uk/crypt/md5/) @@ -280,7 +282,7 @@ The following response parameters are standard to every call and may be returned | message | Sometimes | String | A message that gives additional information about the status of the call. A message parameter will always be returned if the returncode was `FAILED`. A message may also be returned in some cases where returncode was `SUCCESS` if additional information would be helpful.| | messageKey | Sometimes | String | Provides similar functionality to the message and follows the same rules. However, a message key will be much shorter and will generally remain the same for the life of the API whereas a message may change over time. If your third party application would like to internationalize or otherwise change the standard messages returned, you can look up your own custom messages based on this messageKey.| -### create +### `GET` `POST` create Creates a BigBlueButton meeting. @@ -466,7 +468,7 @@ The receiving endpoint should respond with one of the following HTTP codes to in All other HTTP response codes will be treated as transient errors. -### join +### `GET` join Joins a user to the meeting specified in the meetingID parameter. @@ -503,7 +505,7 @@ There is a XML response for this call only when the `redirect` parameter is set ``` -### insertDocument +### `POST` insertDocument This endpoint insert one or more documents into a running meeting via API call @@ -555,7 +557,7 @@ curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID= There is also the possibility of passing the removable and downloadable variables inside the payload, they go in the `document` tag as already demonstrated. The way it works is exactly the same as in the [(POST) create endpoint](#pre-upload-slides) -### isMeetingRunning +### `GET` `POST` isMeetingRunning This call enables you to simply check on whether or not a meeting is running by looking it up with your meeting ID. @@ -584,7 +586,7 @@ http://yourserver.com/bigbluebutton/api/isMeetingRunning?meetingID=test01&ch running can be “true” or “false” that signals whether a meeting with this ID is currently running. -### end +### `GET` `POST` end Use this to forcibly end a meeting and kick all participants out of the meeting. @@ -628,7 +630,7 @@ curl --request POST \ **IMPORTANT NOTE:** You should note that when you call end meeting, it is simply sending a request to the backend (Red5) server that is handling all the conference traffic. That backend server will immediately attempt to send every connected client a logout event, kicking them from the meeting. It will then disconnect them, and the meeting will be ended. However, this may take several seconds, depending on network conditions. Therefore, the end meeting call will return a success as soon as the request is sent. But to be sure that it completed, you should then check back a few seconds later by using the `getMeetingInfo` or `isMeetingRunning` calls to verify that all participants have left the meeting and that it successfully ended. -### getMeetingInfo +### `GET` `POST` getMeetingInfo This call will return all of a meeting's information, including the list of attendees as well as start and end times. @@ -728,7 +730,7 @@ If a meeting is a breakout room itself, then `getMeetingInfo` will also return a ``` -### getMeetings +### `GET` `POST` getMeetings This call will return a list of all the meetings found on this server. @@ -781,7 +783,7 @@ http://yourserver.com/bigbluebutton/api/getMeetings?checksum=1234 ``` -### getRecordings +### `GET` getRecordings Retrieves the recordings that are available for playback for a given meetingID (or set of meeting IDs). Support for pagination was added in 2.6. @@ -896,7 +898,7 @@ Here the `getRecordings` API call returned back two recordings for the meetingID ``` -### publishRecordings +### `GET` publishRecordings Publish and unpublish recordings for a given recordID (or set of record IDs). @@ -924,7 +926,7 @@ Publish and unpublish recordings for a given recordID (or set of record IDs). ``` -### deleteRecordings +### `GET` deleteRecordings Delete one or more recordings for a given recordID (or set of record IDs). @@ -952,7 +954,7 @@ http://yourserver.com/bigbluebutton/api/deleteRecordings?[parameters]&checks ``` -### updateRecordings +### `GET` `POST` updateRecordings Update metadata for a given recordID (or set of record IDs). Available since version 1.1 @@ -979,7 +981,7 @@ Update metadata for a given recordID (or set of record IDs). Available since ver ``` -### getRecordingTextTracks +### `GET` `POST` getRecordingTextTracks Get a list of the caption/subtitle files currently available for a recording. It will include information about the captions (language, etc.), as well as a download link. This may be useful to retrieve live or automatically transcribed subtitles from a recording for manual editing. @@ -1059,7 +1061,7 @@ missingParameter noRecordings : No recording was found matching the provided recording ID. -### putRecordingTextTrack +### `POST` putRecordingTextTrack Upload a caption or subtitle file to add it to the recording. If there is any existing track with the same values for kind and lang, it will be replaced. diff --git a/docs/docs/new-features.md b/docs/docs/new-features.md index d4634fa13e..e7586ce462 100644 --- a/docs/docs/new-features.md +++ b/docs/docs/new-features.md @@ -196,12 +196,6 @@ If `preUploadedPresentationOverrideDefault=false` (or omitted, since `false` is In BigBlueButton 2.6.17/2.7.5 we added a new configuration property for bbb-apps-akka package under `services` called `checkSumAlgorithmForBreakouts`. By default the value is `"sha256"`. It controls the algorithm for checksum calculation for the breakout rooms join link. In case you overwrite bbb-web's `supportedChecksumAlgorithms` property removing sha256 you will need to set a supported algorithm here too. For example if you want to only use `sha512`, set `supportedChecksumAlgorithms=sha512` in `/etc/bigbluebutton/bbb-web.properties` and also set `checkSumAlgorithmForBreakouts="sha512"` in `/etc/bigbluebutton/bbb-apps-akka.conf` and then restart BigBlueButton. -#### Restrict supported content types on BBB API endpoints - -Breaking change: Requests that require both a URL query string and a request body (e.g. CREATE with pre-upload presentation or INSERTDOCUMENT) must provide a Content-Type header with a value of text/xml or application/xml. - -In BigBlueButton 2.6.19/2.7.7 we modified the request validation for the meeting related API endpoints such as CREATE, JOIN, GETMEETINGS, etc. These endpoints now support a limited set of content types that includes text/xml, application/xml, application/x-www-form-urlencoded, and multipart/form-data. By default each endpoint only supports application/x-www-form-urlencoded and multipart/form-data, but individual enpoints can override this and define their own set of supported content types. This is particularily relevant for the CREATE and INSERTDOCUMENT endpoints. The CREATE endpoint supports all of the four content types while INSERTDOCUMENT only supports text/xml and application/xml. Any requests with a content type that differs from the set supported by the target endpoint will be rejected with a new "unsupportedContentType" error. Additonally, any requests that contain both a URL query string AND a request body will be rejected with a checksum error. The exception to this is requests which have a content type of application/xml or text/xml. This is to allow CREATE with pre-upload presentation and INSERTDOCUMENT to continuing functioning as before. - ### Development For information on developing in BigBlueButton, see [setting up a development environment for 2.7](/development/guide).