BigBlueButton/bigbluebutton-Github
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update docs to accurately document API functionality

Browse Source
This commit is contained in:
Paul Trudel 2024-05-08 13:40:46 +00:00
parent 351df9c1f6
commit 52bd10ac23
2 changed files with 16 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/docs/development/api.md
View File

@ -100,7 +100,7 @@ Updated in 2.6:
- **getRecordings** - **Added:** Added support for pagination using `offset`, `limit` - **getRecordings** - **Added:** Added support for pagination using `offset`, `limit`
- **join**: Added `userdata-bbb_hide_presentation_on_join`. - **join**: Added `userdata-bbb_hide_presentation_on_join` and removed support for all HTTP request methods except GET.
## API Data Types ## API Data Types
@ -205,6 +205,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. 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: 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/) - [JavaScript](http://pajhome.org.uk/crypt/md5/)
@ -274,7 +276,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.| | 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.| | 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. Creates a BigBlueButton meeting.
@ -460,7 +462,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. 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. Joins a user to the meeting specified in the meetingID parameter.
@ -497,7 +499,7 @@ There is a XML response for this call only when the `redirect` parameter is set
</response> </response>
``` ```
### insertDocument ### `POST` insertDocument
This endpoint insert one or more documents into a running meeting via API call This endpoint insert one or more documents into a running meeting via API call
@ -549,7 +551,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) 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. This call enables you to simply check on whether or not a meeting is running by looking it up with your meeting ID.
@ -578,7 +580,7 @@ http&#58;//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. 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. Use this to forcibly end a meeting and kick all participants out of the meeting.
@ -622,7 +624,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. **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. This call will return all of a meeting's information, including the list of attendees as well as start and end times.
@ -722,7 +724,7 @@ If a meeting is a breakout room itself, then `getMeetingInfo` will also return a
</response> </response>
``` ```
### getMeetings ### `GET` `POST` getMeetings
This call will return a list of all the meetings found on this server. This call will return a list of all the meetings found on this server.
@ -775,7 +777,7 @@ http&#58;//yourserver.com/bigbluebutton/api/getMeetings?checksum=1234
</response> </response>
``` ```
### 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. 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.
@ -890,7 +892,7 @@ Here the `getRecordings` API call returned back two recordings for the meetingID
</response> </response>
``` ```
### publishRecordings ### `GET` publishRecordings
Publish and unpublish recordings for a given recordID (or set of record IDs). Publish and unpublish recordings for a given recordID (or set of record IDs).
@ -918,7 +920,7 @@ Publish and unpublish recordings for a given recordID (or set of record IDs).
</response> </response>
``` ```
### deleteRecordings ### `GET` deleteRecordings
Delete one or more recordings for a given recordID (or set of record IDs). Delete one or more recordings for a given recordID (or set of record IDs).
@ -946,7 +948,7 @@ http&#58;//yourserver.com/bigbluebutton/api/deleteRecordings?[parameters]&checks
</response> </response>
``` ```
### updateRecordings ### `GET` `POST` updateRecordings
Update metadata for a given recordID (or set of record IDs). Available since version 1.1 Update metadata for a given recordID (or set of record IDs). Available since version 1.1
@ -973,7 +975,7 @@ Update metadata for a given recordID (or set of record IDs). Available since ver
</response> </response>
``` ```
### 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. 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.
@ -1053,7 +1055,7 @@ missingParameter
noRecordings noRecordings
: No recording was found matching the provided recording ID. : 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. 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.

6
docs/docs/new-features.md
View File

@ -292,12 +292,6 @@ Whether you upgrade to BigBlueButton 2.6.14+ via bbb-install-2.6.sh or just thro
In BigBlueButton 2.6.17 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. In BigBlueButton 2.6.17 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 ### Development
For information on developing in BigBlueButton, see [setting up a development environment for 2.6](/development/guide). For information on developing in BigBlueButton, see [setting up a development environment for 2.6](/development/guide).