New API methods/parameters in BBB 0.81 and the docs

473 views
Skip to first unread message

Leonardo Daronco

unread,
Jan 8, 2014, 1:56:01 PM1/8/14
to bigblueb...@googlegroups.com

Hi,

I've been updating the API Mate (https://github.com/mconf/api-mate) to include the new API methods and parameters from BBB 0.81 and I have a few questions and comments regarding the API and the docs.

- The method 'setConfigXML' receives as parameters 'meetingID' and 'configXML'. The docs say that these parameters should be in the body of the HTTP call that should be sent via POST, and they should be signed with a checksum. I tried this at first but the API returns an error if there's no 'configXML'  in the *URL*. I ended up setting the 'meetingID' and the 'configXML' in the URL and removed them from the body of the POST and it all works. So I'm not sure if the docs are wrong or bigbluebutton-web is not doing exactly what it should do. I also had a checksum error if I set the parameters in the wrong order in the URL: for some reason 'configXML' has to come before 'meetingID'. See the error messages below:

When there's no 'configXML' in the URL (even if there's a configXML in the POST data):
<response><returncode>FAILED</returncode><messageKey>configXMLError</messageKey><message>You did not pass a config XML</message></response>

When the parameters are not properly ordered in a 'setConfigXML' call:
<response><returncode>FAILED</returncode><messageKey>configXMLChecksumError</messageKey><message>configXMLChecksumError: request did not pass the checksum security check.</message></response>

I did this in a few servers and then confirmed this is what happens in http://test-install.blindsidenetworks.com/.


- It's not the first time that I had some trouble figuring out exactly how BBB encodes the URLs before calculating the checksum. The way it calculates the checksum is very well documented, but the way it encodes the parameters is not very clear. I know now that a very standard method from a standard library of Java is used, but when you have to do exactly the same encoding from another language it gets harder. Javascript, for instance, has at least three possible methods to encode parameters to use them in URLs: 'escape' (not really the best, but works), 'encodeURI' and 'encodeURIComponent'. As far as I know, neither will generate exactly the same output of the method BBB uses. Take a look at this entry (http://stackoverflow.com/questions/607176/java-equivalent-to-javascripts-encodeuricomponent-that-produces-identical-output) on stackoverflow, for instance, it helped me figure out the problem.
I had problems specifically with the XML set in 'setConfigXML', because it has a lot of "unusual" characters that need to be encoded.
The point in all this is that I don't think BBB should encode the parameters before calculating the checksum, instead it should do exactly the opposite: calculate the checksum with the URLs exactly as they are before being encoded, with spaces and everything. Then it doesn't really matter the method used to encode the URL (as long as BBB can decode it).
Not entirely sure about it though, what do you think? Is there a clear reason for having to encode the URL before calculating the checksum?


A few other small things that could be improved in the docs (http://code.google.com/p/bigbluebutton/wiki/API):

- the new parameters for 'join', that are 'configToken' and 'avatarURL', are commented at the top, but only the first is described in the table that describes all parameters for this method.

- the new parameters for 'create', that are 'redirectClient' and 'clientURL', are commented at the top, but they are not described in the table that describes all parameters for this method.


Thanks guys, regards,
--
Leonardo Crauss Daronco

Richard Alam

unread,
Jan 9, 2014, 11:40:07 AM1/9/14
to bigblueb...@googlegroups.com
Hi Leonardo,


On Wednesday, January 8, 2014 1:56:01 PM UTC-5, Daronco wrote:

Hi,

I've been updating the API Mate (https://github.com/mconf/api-mate) to include the new API methods and parameters from BBB 0.81 and I have a few questions and comments regarding the API and the docs.

- The method 'setConfigXML' receives as parameters 'meetingID' and 'configXML'. The docs say that these parameters should be in the body of the HTTP call that should be sent via POST, and they should be signed with a checksum. I tried this at first but the API returns an error if there's no 'configXML'  in the *URL*. I ended up setting the 'meetingID' and the 'configXML' in the URL and removed them from the body of the POST and it all works. So I'm not sure if the docs are wrong or bigbluebutton-web is not doing exactly what it should do. I also had a checksum error if I set the parameters in the wrong order in the URL: for some reason 'configXML' has to come before 'meetingID'. See the error messages below:

When there's no 'configXML' in the URL (even if there's a configXML in the POST data):
<response><returncode>FAILED</returncode><messageKey>configXMLError</messageKey><message>You did not pass a config XML</message></response>



 

When the parameters are not properly ordered in a 'setConfigXML' call:
<response><returncode>FAILED</returncode><messageKey>configXMLChecksumError</messageKey><message>configXMLChecksumError: request did not pass the checksum security check.</message></response>

I did this in a few servers and then confirmed this is what happens in http://test-install.blindsidenetworks.com/.




 

- It's not the first time that I had some trouble figuring out exactly how BBB encodes the URLs before calculating the checksum. The way it calculates the checksum is very well documented, but the way it encodes the parameters is not very clear. I know now that a very standard method from a standard library of Java is used, but when you have to do exactly the same encoding from another language it gets harder. Javascript, for instance, has at least three possible methods to encode parameters to use them in URLs: 'escape' (not really the best, but works), 'encodeURI' and 'encodeURIComponent'. As far as I know, neither will generate exactly the same output of the method BBB uses. Take a look at this entry (http://stackoverflow.com/questions/607176/java-equivalent-to-javascripts-encodeuricomponent-that-produces-identical-output) on stackoverflow, for instance, it helped me figure out the problem.

I agree. I've been looking at best practices in defining APIs. Right now, even the sequence of parameters isn't defined. I think parameters when building the base string should be arranged alphabetically.
You have to either look at the code or doc. And in this case, not documented. :)
 

I had problems specifically with the XML set in 'setConfigXML', because it has a lot of "unusual" characters that need to be encoded.
The point in all this is that I don't think BBB should encode the parameters before calculating the checksum, instead it should do exactly the opposite: calculate the checksum with the URLs exactly as they are before being encoded, with spaces and everything. Then it doesn't really matter the method used to encode the URL (as long as BBB can decode it).
Not entirely sure about it though, what do you think? Is there a clear reason for having to encode the URL before calculating the checksum?


There's no reason to encode before. I think I encoded it then tested and worked. So I left it at that.

Going forward, we can come up with rules on how to design and implement the API based on how others do it...Do you have any ideas?

 

A few other small things that could be improved in the docs (http://code.google.com/p/bigbluebutton/wiki/API):

- the new parameters for 'join', that are 'configToken' and 'avatarURL', are commented at the top, but only the first is described in the table that describes all parameters for this method.

- the new parameters for 'create', that are 'redirectClient' and 'clientURL', are commented at the top, but they are not described in the table that describes all parameters for this method.


I'll edit the wiki on how to use this.

Richard

David Busby

unread,
Jan 14, 2014, 7:07:28 PM1/14/14
to bigblueb...@googlegroups.com
Looking on my system (0.81 final) I see that mapping in the Groovy file, pointing for "setConfigXML".  When I make an API call to "api/setConfigXML" I am given a 404 error.  However when I POST to "api/setConfigXML.xml" it works.  I discovered this reading `bbb-api-demo/src/main/webapp/bbb_api.jsp`  

There is a PHP script to (in archive.zip file) floating around this group too, it also points to "api/setConfigXML.xml" but the name used for building a checksum is just "setConfigXML".  It also does some interesting URL encoding thing and has some kind of exception list in there, it uses PHP urlencode(), then undoes 20 specific encodings then passes through urlencode() again.  Not what I'd expect.  Other API calls the basename part of the URI matches the function parameter on the checksum (like for create or join APIs)

I expected a POST, no ".xml" extension, no parameters in the query string, three POSTed fields, configXML, meetingID and checksum where checksum was constructed from concatenated fields in alphabetical order (like Amazon does).  I would not expect to have to encode the XML twice, with an exception rule

my $0.02

Leonardo Daronco

unread,
Jan 22, 2014, 1:24:16 PM1/22/14
to bigblueb...@googlegroups.com
Hi,


On Thu, Jan 9, 2014 at 2:40 PM, Richard Alam <ritz...@gmail.com> wrote:
Hi Leonardo,


On Wednesday, January 8, 2014 1:56:01 PM UTC-5, Daronco wrote:

Hi,

I've been updating the API Mate (https://github.com/mconf/api-mate) to include the new API methods and parameters from BBB 0.81 and I have a few questions and comments regarding the API and the docs.

- The method 'setConfigXML' receives as parameters 'meetingID' and 'configXML'. The docs say that these parameters should be in the body of the HTTP call that should be sent via POST, and they should be signed with a checksum. I tried this at first but the API returns an error if there's no 'configXML'  in the *URL*. I ended up setting the 'meetingID' and the 'configXML' in the URL and removed them from the body of the POST and it all works. So I'm not sure if the docs are wrong or bigbluebutton-web is not doing exactly what it should do. I also had a checksum error if I set the parameters in the wrong order in the URL: for some reason 'configXML' has to come before 'meetingID'. See the error messages below:

When there's no 'configXML' in the URL (even if there's a configXML in the POST data):
<response><returncode>FAILED</returncode><messageKey>configXMLError</messageKey><message>You did not pass a config XML</message></response>

The proper call is api/setConfigXML

No sure what you mean, all I said was for api/setConfigXML...
 

When the parameters are not properly ordered in a 'setConfigXML' call:
<response><returncode>FAILED</returncode><messageKey>configXMLChecksumError</messageKey><message>configXMLChecksumError: request did not pass the checksum security check.</message></response>

I did this in a few servers and then confirmed this is what happens in http://test-install.blindsidenetworks.com/.



Apparently this method "isConfigXMLChecksumSame" is never called :D
Tried to grep it in the entire code and it only shows once, in its declaration.

The error was actually here https://github.com/bigbluebutton/bigbluebutton/blob/master/bigbluebutton-web/grails-app/controllers/org/bigbluebutton/web/controllers/ApiController.groovy#L850
It seems like this is where it gets the parameters from the URL instead of getting from the body of the request.
 

- It's not the first time that I had some trouble figuring out exactly how BBB encodes the URLs before calculating the checksum. The way it calculates the checksum is very well documented, but the way it encodes the parameters is not very clear. I know now that a very standard method from a standard library of Java is used, but when you have to do exactly the same encoding from another language it gets harder. Javascript, for instance, has at least three possible methods to encode parameters to use them in URLs: 'escape' (not really the best, but works), 'encodeURI' and 'encodeURIComponent'. As far as I know, neither will generate exactly the same output of the method BBB uses. Take a look at this entry (http://stackoverflow.com/questions/607176/java-equivalent-to-javascripts-encodeuricomponent-that-produces-identical-output) on stackoverflow, for instance, it helped me figure out the problem.

I agree. I've been looking at best practices in defining APIs. Right now, even the sequence of parameters isn't defined. I think parameters when building the base string should be arranged alphabetically.
You have to either look at the code or doc. And in this case, not documented. :)
 

I had problems specifically with the XML set in 'setConfigXML', because it has a lot of "unusual" characters that need to be encoded.
The point in all this is that I don't think BBB should encode the parameters before calculating the checksum, instead it should do exactly the opposite: calculate the checksum with the URLs exactly as they are before being encoded, with spaces and everything. Then it doesn't really matter the method used to encode the URL (as long as BBB can decode it).
Not entirely sure about it though, what do you think? Is there a clear reason for having to encode the URL before calculating the checksum?


There's no reason to encode before. I think I encoded it then tested and worked. So I left it at that.

Going forward, we can come up with rules on how to design and implement the API based on how others do it...Do you have any ideas?


Yeah, I thought this was the case :)
I don't have a vast knowledge of other APIs, the one that I know the most is BigBlueButton's. It is pretty ok, it does what it says it does and works. But I think some things could be changed to make it more robust and maybe clearer to users.
When you think it's time to review the API and possibly brake backwards compatibility I can help studying other APIs to figure out the best way to do it.


So, after all this, and looking at what David said as well, I still have to ask this one again:
- 'setConfigXML' receives and uses the parameters from the URL, but the documentation says the parameters should be in the POST data. Which one is wrong, the code or the documentation? (Or is it me?)


Regards,
--
Leonardo Crauss Daronco


--
You received this message because you are subscribed to the Google Groups "BigBlueButton-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bigbluebutton-...@googlegroups.com.
To post to this group, send email to bigblueb...@googlegroups.com.
Visit this group at http://groups.google.com/group/bigbluebutton-dev.
For more options, visit https://groups.google.com/groups/opt_out.

Richard Alam

unread,
Jan 23, 2014, 1:52:08 PM1/23/14
to BigBlueButton-dev
Ok. Here's the form I used to test the api. Maybe it's my poor HTTP knowledge that's tripping you up. :) I might be doing a GET here instead of a POST and I call it a POST since the example I got the code from
was using POST.


Regarding the .xml extension in setConfigXML.xml, that's the content-negotiation (http://grails.org/doc/latest/guide/single.html#contentNegotiation).

Richard
 

Regards,
--
Leonardo Crauss Daronco


On Tue, Jan 14, 2014 at 10:07 PM, David Busby <david...@edoceo.com> wrote:
Looking on my system (0.81 final) I see that mapping in the Groovy file, pointing for "setConfigXML".  When I make an API call to "api/setConfigXML" I am given a 404 error.  However when I POST to "api/setConfigXML.xml" it works.  I discovered this reading `bbb-api-demo/src/main/webapp/bbb_api.jsp`  

There is a PHP script to (in archive.zip file) floating around this group too, it also points to "api/setConfigXML.xml" but the name used for building a checksum is just "setConfigXML".  It also does some interesting URL encoding thing and has some kind of exception list in there, it uses PHP urlencode(), then undoes 20 specific encodings then passes through urlencode() again.  Not what I'd expect.  Other API calls the basename part of the URI matches the function parameter on the checksum (like for create or join APIs)

I expected a POST, no ".xml" extension, no parameters in the query string, three POSTed fields, configXML, meetingID and checksum where checksum was constructed from concatenated fields in alphabetical order (like Amazon does).  I would not expect to have to encode the XML twice, with an exception rule

my $0.02

--
You received this message because you are subscribed to the Google Groups "BigBlueButton-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bigbluebutton-...@googlegroups.com.
To post to this group, send email to bigblueb...@googlegroups.com.
Visit this group at http://groups.google.com/group/bigbluebutton-dev.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "BigBlueButton-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bigbluebutton-...@googlegroups.com.
To post to this group, send email to bigblueb...@googlegroups.com.
Visit this group at http://groups.google.com/group/bigbluebutton-dev.
For more options, visit https://groups.google.com/groups/opt_out.
Reply all
Reply to author
Forward
0 new messages