-
Notifications
You must be signed in to change notification settings - Fork 40
JSON API
Notice: The API is a work-in-progress feature, being developed incrementally starting on version 2.2.0.
BigbluebuttonRails includes a json API to allow external access to resources in the gem. As of writing (06/2017), the API is in an initial stage and includes just a few methods to list and access rooms as a guest. These methods are all public, so there's still no authentication implemented in the API.
The API follows the conventions described by jsonapi.org.
By default all API methods are located under the endpoint /api/conference
. This can be easily changed by the application that uses the gem when calling bigbluebutton_api_routes
in its config/routes.rb
.
By default, the API will reject all requests until you set up the authentication. To do so, set a value to BigbluebuttonRails.configuration.api_secret
.
There are three options:
- Leave it as
nil
to disable the API. - Set it to an empty string to disable authentication and allow all API requests;
- Set it to any non empty string to enable authentication.
After setting a value to the api_secret
, this value should be passed in the HTTP header Authorization
in all API calls. The header should follow the format (assuming "123456789abc" is the value set in api_secret
):
Authorization: Bearer 123456789abc
In curl this can be done with, for example:
curl -X GET "http://localhost:3000/api/conference/rooms.json" -H "Authorization: Bearer 123456789abc"
Returns a list of rooms available.
Name | Required? | Description |
---|---|---|
sort |
No | Sort the results. Available options: name , activity (for inverse order, use -name ). Default: name . |
page[size] |
No | The number of results to return in a "page" of results. Default: 10. |
page[number] |
No | The number of the page to be returned. Default: 1. |
filter[terms] |
No | A list of terms separated by commas (, ) to filter the results. Will match against the name and the URL of the room and return the results ordered by number of matches. |
http://localhost:3000/api/conference/rooms.json?sort=activity
http://localhost:3000/api/conference/rooms.json?sort=-name&page[size]=1
http://localhost:3000/api/conference/rooms.json?sort=activity&page[size]=3&page[number]=2
http://localhost:3000/api/conference/rooms.json?filter[terms]=english,languages
http://localhost:3000/api/conference/rooms.json?sort=activity&page[size]=2
{
"links":{
"self":"http://localhost:3000/api/conference/rooms.json?sort=activity&page%5Bsize%5D=2",
"next":"http://localhost:3000/api/conference/rooms.json?sort=activity&page%5Bsize%5D=2&page%5Bnumber%5D=2",
"first":"http://localhost:3000/api/conference/rooms.json?sort=activity&page%5Bsize%5D=2&page%5Bnumber%5D=1"
},
"data":[
{
"type":"room",
"id":"messi",
"attributes":{
"name":"Lionel Messi",
"private":false
},
"relationships":{
"owner":{
"data":{
"type":"user",
"id":"messi",
"attributes":{
"name":"Lionel Messi"
}
},
"links":{
"self":"/users/messi"
}
}
},
"links":{
"self":"/conference/messi"
}
},
{
"type":"room",
"id":"michael-jordan",
"attributes":{
"name":"Michael Jordan's Room",
"private":true
},
"relationships":{
"owner":{
"data":{
"type":"user",
"id":"michael-jordan",
"attributes":{
"name":"Michael Jordan"
}
},
"links":{
"self":"/users/jordan"
}
}
},
"links":{
"self":"/conference/michael"
}
}
]
}
Checks if a room is currently running.
Name | Required? | Description |
---|---|---|
:id |
Yes | The ID of the target room. |
http://localhost:3000/api/conference/rooms/messi/running.json
http://localhost:3000/api/conference/rooms/messi/running.json
{
"data":{
"type":"room",
"id":"messi",
"attributes":{
"running":false
}
}
}
Fetches the link to join a conference as a guest. Will only work if the room is already running.
Name | Required? | Description |
---|---|---|
:id |
Yes | The ID of the target room. |
name |
Yes | The name of the user that is joining. |
key |
Yes (for private rooms only) | The room's access key. Not required if the room is not private. |
meta_* or meta-*
|
No | Metadata attributes. They are passed to BigBlueButton as userdata- attributes in the join API call. |
http://localhost:3000/api/conference/rooms/messi/join.json?name=Any%20Guest
http://localhost:3000/api/conference/rooms/messi/join.json?name=Any%20Guest&key=guest123
http://localhost:3000/api/conference/rooms/messi/join.json?name=Any%20Guest&meta_organization=My%20Company&meta_important_person=1
http://localhost:3000/api/conference/rooms/daronco/join.json?name=Any%20Guest&key=guest123
{
"data":{
"type":"join-url",
"id":"http://test-install.blindsidenetworks.com/bigbluebutton/api/join?createTime=1496674407566&fullName=Any+Guest&meetingID=b2lski96-a3d2-45f7-bf17-bda72c3b7914-1397502282&password=99e73247-5c74-4122-aafa-b9ciajd77960&checksum=749770eb0b928df8bb5daec884c0d2071b020699"
}
}
{
"errors":[
{
"status":"400",
"title":"Meeting not running",
"detail":"There's no meeting currently running in this room"
}
]
}
{
"errors":[
{
"status":"403",
"title":"Invalid key",
"detail":"The key informed is not valid for this room"
}
]
}
{
"errors":[
{
"status":"400",
"title":"Missing parameters",
"detail":"You did not inform one or more required parameters"
}
]
}
{
"errors":[
{
"status":"404",
"title":"Resource not found",
"detail":"Could not find the target room"
}
]
}
{
"errors":[
{
"status":"400",
"title":"Invalid pagination parameters",
"detail":"One or more pagination parameters are wrong"
}
]
}