Merge pull request #392 from GuiLeme/deprecation-of-passwords

[deprecation-of-passwords] Updating docs on 2.4

Author: antobinary

_data/create.yml

@@ -9,14 +9,12 @@
   description: "A meeting ID that can be used to identify this meeting by the 3rd-party application. <br><br> This must be unique to the server that you are calling: different active meetings can not have the same meeting ID. <br><br> If you supply a non-unique meeting ID (a meeting is already in progress with the same meeting ID), then if the other parameters in the create call are identical, the create call will succeed (but will receive a warning message in the response). The create call is idempotent: calling multiple times does not have any side effect.  This enables a 3rd-party applications to avoid checking if the meeting is running and always call create before joining each user.<br><br> Meeting IDs should only contain upper/lower ASCII letters, numbers, dashes, or underscores.  A good choice for the meeting ID is to generate a <a href=\"http://en.wikipedia.org/wiki/Globally_unique_identifier\">GUID</a> value as this all but guarantees that different meetings will not have the same meetingID."
 
 - name: "attendeePW"
-  required: "(recommended)"
   type: "String"
-  description: "The password that the <a href=\"#join\">join</a> URL can later provide as its <code class=\"language-plaintext highlighter-rouge\">password</code> parameter to indicate the user will join as a viewer.  If no <code class=\"language-plaintext highlighter-rouge\">attendeePW</code> is provided, the <code class=\"language-plaintext highlighter-rouge\">create</code> call will return a randomly generated <code class=\"language-plaintext highlighter-rouge\">attendeePW</code> password for the meeting."
+  description: "<b>[DEPRECATED]</b> The password that the <a href=\"#join\">join</a> URL can later provide as its <code class=\"language-plaintext highlighter-rouge\">password</code> parameter to indicate the user will join as a viewer.  If no <code class=\"language-plaintext highlighter-rouge\">attendeePW</code> is provided, the <code class=\"language-plaintext highlighter-rouge\">create</code> call will return a randomly generated <code class=\"language-plaintext highlighter-rouge\">attendeePW</code> password for the meeting."
 
 - name: "moderatorPW"
-  required: "(recommended)"
   type: "String"
-  description: "The password that will <a href=\"#join\">join</a> URL can later provide as its <code class=\"language-plaintext highlighter-rouge\">password</code> parameter to indicate the user will as a moderator.  if no <code class=\"language-plaintext highlighter-rouge\">moderatorPW</code> is provided, <code class=\"language-plaintext highlighter-rouge\">create</code> will return a randomly generated <code class=\"language-plaintext highlighter-rouge\">moderatorPW</code> password for the meeting."
+  description: "<b>[DEPRECATED]</b> The password that will <a href=\"#join\">join</a> URL can later provide as its <code class=\"language-plaintext highlighter-rouge\">password</code> parameter to indicate the user will as a moderator.  if no <code class=\"language-plaintext highlighter-rouge\">moderatorPW</code> is provided, <code class=\"language-plaintext highlighter-rouge\">create</code> will return a randomly generated <code class=\"language-plaintext highlighter-rouge\">moderatorPW</code> password for the meeting."
 
 - name: "welcome"
   required: false

_data/end.yml

@@ -5,4 +5,4 @@
 - name: "password"
   required: true
   type: "String"
-  description: "The moderator password for this meeting. You can not end a meeting using the attendee password."
+  description: "<b>[DEPRECATED]</b> The moderator password for this meeting. You can not end a meeting using the attendee password."

_data/join.yml

@@ -11,7 +11,7 @@
 - name: "password"
   required: true
   type: "String"
-  description: "This password value is used to determine the role of the user based on whether it matches the moderator or attendee password.  Note: This parameter is *not* required when the role parameter is passed."
+  description: "<b>[DEPRECATED]</b> This password value is used to determine the role of the user based on whether it matches the moderator or attendee password.  Note: This parameter is <b>not</b> required when the role parameter is passed."
 
 - name: "role"
   required: true

_posts/2.4/2021-06-09-new.md

@@ -163,6 +163,8 @@ Blurring the background
 <img src="/images/24-background-blur-3.png" alt="Background blur for webcam" />
 <br /><br />
 
+### 
+
 ## Engagement
 
 ### Improved Layout Manager
@@ -381,3 +383,27 @@ The best ways to contribute at the current time are:
 - Try out installing BigBlueButton 2.4 and see if you spot any issues
 - Help test a [2.4 pull request](https://github.com/bigbluebutton/bigbluebutton/pulls?q=is%3Aopen+is%3Apr+milestone%3A%22Release+2.4%22) in your development environment
   <!-- TODO create a GitHub label for contributions-welcome and link here -->
+
+## API
+
+### Deprecation of password
+
+Even though it is still possible to create a meeting with a password, it is now being deprecated, and it is not required anymore. So here are some explanations to better illustrate this update:
+
+- **Create** - It is possible and recommended to not use the passwords while creating the request:
+
+```url 
+https://bbb.example.com/bigbluebutton/api/create?allowStartStopRecording=true&attendeePW=ap&moderatorPW=mp&... &checksum=
+```
+or 
+```url 
+https://bbb.example.com/bigbluebutton/api/create?allowStartStopRecording=true&... &checksum=
+```
+
+- **Join** - These requests don't need to follow the `/create` endpoint, on the grounds that it has its own parameter to know the role of the user. See the explanation down below:
+
+  - In any cases, if the `role` parameter is sent along, it will be respected, even if `password` is passed too;
+  - If the `role` parameter is not passed in the request, and the password exists (i.e., it has been sent in `/create` endpoint), then the password is mandatory for the `/join` endpoint to identify which role the user has.
+  - If the password does not exist (i.e., it was not defined in `/create` endpoint), then the `role` parameter is mandatory, otherwise it is not possible to enter a meeting.
+
+- **End** - the password is really not used here. But, if it was set (in the `/create` endpoint) and passed along in the `end` endpoint, it will be validated, otherwise, it won't.