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.

Authentication

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"

Available methods

GET rooms.json

Returns a list of rooms available.

Parameters:

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.

Examples:

• 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

Response example:

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"
         }
      }
   ]
}

GET rooms/:id/running.json

Checks if a room is currently running.

Parameters:

Name	Required?	Description
:id	Yes	The ID of the target room.

Examples:

• http://localhost:3000/api/conference/rooms/messi/running.json

Response example:

http://localhost:3000/api/conference/rooms/messi/running.json

{
   "data":{
      "type":"room",
      "id":"messi",
      "attributes":{
         "running":false
      }
   }
}

POST rooms/:id/join.json

Fetches the link to join a conference as a guest. Will only work if the room is already running.

Parameters:

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.

Examples:

• 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

Response example:

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

Meeting not running

{
   "errors":[
      {
         "status":"400",
         "title":"Meeting not running",
         "detail":"There's no meeting currently running in this room"
      }
   ]
}

Invalid access key

{
   "errors":[
      {
         "status":"403",
         "title":"Invalid key",
         "detail":"The key informed is not valid for this room"
      }
   ]
}

Missing parameters

{
   "errors":[
      {
         "status":"400",
         "title":"Missing parameters",
         "detail":"You did not inform one or more required parameters"
      }
   ]
}

Room not found

{
   "errors":[
      {
         "status":"404",
         "title":"Resource not found",
         "detail":"Could not find the target room"
      }
   ]
}

Invalid pagination

{
   "errors":[
      {
         "status":"400",
         "title":"Invalid pagination parameters",
         "detail":"One or more pagination parameters are wrong"
      }
   ]
}