Guestroam service provides a REST API to let you incorporate guest creation into your institution's portal or in dedicaded "kiosk".

This document describes howto use this API using shell commands, python library or html/javascript.

The full reference of the API can be found here.

Requirements and constraints

Every API actions uses token authentication. Guestroam's manager only receives a token.

A manager can get his API token here.

The API only provides sufficient actions to create new guest requests and credentials without the need of human intervention.

API using python shell client

Coreapi-cli is a python based command line client that will let you access guestroam API.

Install coreapi-cli

You can install it using pip:

 $ pip install coreapi-cli

Add your token credential

$ coreapi credentials add www.guestroam.be 'Token mytoken' 

Verify that credential is correctly set:

$ coreapi credentials show 

Credentials                 
www.guestroam.be "Token mytoken"

Load the schema document

 $ coreapi get https://www.guestroam.be/api/docs/ 

Guestroam API "https://www.guestroam.be/api/docs/"
    credentials: {
        list()
        read(id)
        resend(id)
    }
    departments: {
        list()
        read(id)
    }
    guests: {
        list()
        create(department, firstname, lastname, email, gsm_number, end_date, start_date, contact, [language])
        read(id)
    }

Create new guest request and credential

To create a new guest request, you need to have the ID of the request's associated department:

$ coreapi action departments list

[
    {
        "id": 1,
        "name": "ALL",
        "enabled": true,
        "ephemeral": false,
        "start_date": null,
        "end_date": null
    },
    {
        "id": 4,
        "name": "LOGISTIC",
        "enabled": true,
        "ephemeral": false,
        "start_date": null,
        "end_date": null
    }
]
Once having the department ID, we can now create our guest:
$ coreapi action guests create -p department=1 -p firstname="Muppets" \
-p lastname="Animal" -p email="animals@muppets.show" -p gsm_number="+32123456789"  \
-p start_date="2019-09-21" -p end_date="2019-09-22" -p contact="Kermit" -p language="en"

where

  • start_date / end_date is formatted as: YYYY-MM-DD;
  • gsm_number is formatted as : +XX12356789 where XX is international prefix number;
  • language is either "nl", "fr" or "en".

As a result, the API will return the new guest request and the guest credential back.

The request is automatically approved and, credentials are directly sent to the guest.

 
{
    "credential": {
        "username": "thix5l@guestroam.be",
        "end_date": "2019-09-22",
        "enabled": true,
        "institution": 1,
        "start_date": "2019-09-21",
        "password": "thai1Ahz",
        "id": 89
    },
    "request": {
        "id": 141,
        "department": 1,
        "firstname": "Muppets",
        "lastname": "Animal",
        "email": "animals@muppets.show",
        "gsm_number": "+32123456789",
        "end_date": "2019-09-22",
        "start_date": "2019-09-21",
        "contact": "Kermit",
        "language": "en",
        "institution": 1
    
    }
}
  

API using Python

Install API python module

To use the gestroam API with python, you need to install the coreapi python module:

$ pip install coreapi

guestroam-api.py's example:

import coreapi

# set your authorization token
token='MYTOKEN'

# create an auth object
auth=coreapi.auth.TokenAuthentication(scheme='Token', token=token)

# instanciate api client
client = coreapi.Client(auth=auth)

# get the schema

schema = client.get("https://www.guestroam.be/api/docs/")

# get list of departemnts

action=["departments","list"]
result=client.action(schema,action)

print ("Guestroam Departments List\n")
print ("--------------------------\n")
print (result)

# get list of guest request 

action=["guests","list"]
result=client.action(schema,action)

print ("Guestroam Guets list \n")
print ("---------------------\n")
print (result)

# get list of credentials

action=["credentials","list"]
result=client.action(schema,action)

print ("Guestroam credential list \n")
print ("--------------------------\n")
print (result)

# create a new guest

action=["guests","create"]
params={
 "department":1,
 "firstname":"Muppets",
 "lastname":"Animal",
 "email":"animal@muppet.show", 
 "gsm_number": "+32123456789",
 "start_date": "2019-09-25",
 "end_date": "2019-09-27",
 "contact": "Kermit",
 "language":"en"
 }

result=client.action(schema, action, params=params)
print ("Guestroam guest creation \n")
print ("---------------------------")
print (result)

Using API in Javascript/HTML page

Simpe HTML page to get the list of departments:

<html>
<head>
    <title>Belnet GuestRoam  API test retrieve department list</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="description" content="Belnet Guestroam API Test" >
    <meta name="keywords" content="belnet, govroam,eduroam,guestroam" > 
    <script src="https://code.jquery.com/jquery-3.3.1.js"></script>
    <script src = "https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
    <link rel="stylesheet" type="text/css" href="https://cdn.datatables.net/1.10.19/css/jquery.dataTables.min.css">
    <script src="https://cdn.datatables.net/1.10.19/js/jquery.dataTables.min.js"></script>

    <link rel="stylesheet" href="https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.css">
    <script src="https://www.guestroam.be/static/rest_framework/js/coreapi-0.1.1.js"></script>
    <script src="https://www.guestroam.be/api/docs/schema.js"></script>
    <script>
    
      $(document).ready( function(){
          var credential_table=$('#credential').DataTable({
             "paging": false,
             "scrollX": true,

          });
          var coreapi = window.coreapi  // Loaded by `coreapi.js`
          var schema = window.schema 
          var auth= new coreapi.auth.TokenAuthentication({
            scheme:'Token',
            token:'MYTOKEN'
          });
          var client= new coreapi.Client({auth:auth})
          var action = ["departments", "list"]
          client.action(schema, action).then(function(result) {
            credential_table.clear(); 
            result.forEach(function(element){
              console.log(element)
              credential_table.row.add([element.id,element.name,element.enabled,element.ephemeral,element.start_date,element.end_date]).draw();
            });
            
          // Return value is in 'result'
            
          });
      });
    </script>    
</head>
<body>
<table id="credential" class="display" style="width:100%">
  <thead>
   <tr>
   <th>id</th>
   <th>name</th>
   <th>enabled</th>
   <th>ephemeral</th>
   <th>start_date</th>
   <th>end_date</th>
   </tr>
 </thead>
 <tbody>
 </tbody>
  </table>
</body>
</html>

Simple HTML page using a form to create new guests:

<html>
<head>
    <title>Belnet GuestRoam  API test create new request</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="description" content="Belnet Guestroam API Test" >
    <meta name="keywords" content="belnet, govroam,eduroam,guestroam" > 
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
    <script src="https://www.guestroam.be/static/rest_framework/js/coreapi-0.1.1.js"></script>
    <script src="https://www.guestroam.be/api/docs/schema.js"></script>
    <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous"></script>
    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
    <script src = "https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
   <link rel="stylesheet" href="https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.css"> 
    <script>
    
      $(document).ready( function(){
          var coreapi = window.coreapi  // Loaded by `coreapi.js`
          var schema = window.schema 
          var auth= new coreapi.auth.TokenAuthentication({
            scheme:'Token',
            token:'MYTOKEN'
          });
          var client= new coreapi.Client({auth:auth})
          // populate the department 
          var action=['departments','list']
          client.action(schema,action).then(function(result){
            result.forEach(function(item,index){
              $("#department").append("<option value='"+item.id+"'>"+item.name+"</option>");
            });            
          }
          );

          $( "#start_date" ).datepicker( {
              maxDate: "+1M",
              minDate: 0,
              dateFormat:  "yy-mm-dd", 
          });
          $( "#start_date" ).focus(function() {
          $( "#start_date" ).datepicker("show");
          });
          $( "#end_date" ).datepicker( {
              maxDate: "+1M",
              minDate: 0,
              dateFormat:  "yy-mm-dd", 
          });
          $( "#end_date" ).focus(function() {
          $( "#end_date" ).datepicker("show");
          });
          $("#submit_button").on('click',function(event){
            event.preventDefault();
            var action =["guests","create"];
            var params = {
                 firstname: $("#firstname").val(),
                 lastname: $("#lastname").val(),
                 email: $("#email").val(),
                 gsm_number:  $("#gsm").val(),
                 start_date:  $("#start_date").val(),
                 end_date:  $("#end_date").val(),
                 contact: $("#contact").val(),
                 language: $("#language").val(),
                 department:$("#department").val(),
            }
            console.log(params);
            client.action(schema, action, params).then(function(result) {
             //Return value is in 'result'
             $("#request_result").text(JSON.stringify(result));
             $("#request_result").show();
             console.log(result);
            })

            
          });
      });
    </script>    
</head>
<body>
<div id="container" class="container-fluid">
<form>
    <div class="form-group">
    <label for="firstname">FirstName</label>
    <input class="form-control" id="firstname" placeholder="Enter Your Firstname" required>
    </div>
    <div class="form-group">
    <label for="">lastname</label>
    <input class="form-control" id="lastname" placeholder="Enter Your Lastname" required>
    </div>
    <div class="form-group">
    <label for="">Email</label>
    <input class="form-control" id="email" placeholder="Enter Your Email" required>
    </div>
    <div class="form-group">
    <label for="">GSM Number</label>
    <input class="form-control" id="gsm" placeholder="Enter Your GSM number" required>
    </div>
    <div class="form-group">
    <label for="">Start Date</label>
    <input class="form-control" id="start_date" placeholder="YYYY-MM-DD" required>
    </div>
    <div class="form-group">
    <label for="">End Date</label>
    <input class="form-control" id="end_date" placeholder="YYYY-MM-DD" required>
    </div>
    <div class="form-group">
    <label for="">Language</label>
    <select id="language" required>
    <option value="en" >English</option>
    <option value="nl">Dutch</option>
    <option value="fr">French</option> 
    </select>
    </div>
    <div class="form-group">
    <label for="">Contact</label>
    <input class="form-control" id="contact" placeholder="contact into institution" required>
    </div>
    <div class="form-group">
    <label for="">Departement ID</label>
    <select id="department" required>
    </select>
    </div>
    <button id="submit_button" class="btn btn-primary">Submit</button>
</form>
</div>
<div id="result"> 
   <code id="request_result" style=" border: solid 1px #000000; border-radius: 4px;padding: 9.5px;display: block;-webkit-box-shadow: 10px 10px 5px 0px rgba(0,0,0,0.75);
   -moz-box-shadow: 10px 10px 5px 0px rgba(0,0,0,0.75);box-shadow: 10px 10px 5px 0px rgba(0,0,0,0.75); margin: 15px; ">
   </code>
</div>

</body>
</html>