SuperOffice REST / WebAPI web services

• 5 minutes to read

 • 5 minutes to read

To successfully use the REST APIs (introduced in SuperOffice version 8), you must pass along credentials in each request header.

Below is an HTML page that contains a few text boxes for determining where, or what version of, the services reside, user name, and password. With this required information, the user can specify a project ID and click the Get button to execute an XMLHttpRequest.

Options

You will need to provide some login information to use the SuperOffice WebAPI.

• BASIC authentication: Base64 Encode SuperOffice username:password
• SOTICKET authentication. Pass the SuperOffice ticket (7T:abc123==) without any encoding.
• BEARER authentication. Online only. Pass along an access token (7A:abc123==) from SuperID.
• NEGOTIATE / NTLM authentication. Onsite only. Initiates an Active Directory user authentication.

Auth type	Example	Onsite	Online
No header		x	x
Basic	YWrtMdo=	x
SOTicket	7T:xyz123abc==	x	x
Bearer	8A:xyz123abc==		x
Negotiate		x

No Authorize header on a request means that you either:

• have IIS configured to handle identity so that you can log in with your Active Directory, or
• that you send an X-XSRF-TOKEN header to prove that you have access to a logged-in session

Note

You must explicitly enable the authentication methods that you want to use in the web.config file.

Basic

The setRequestHeader method is used to add the Authorization header key entry with a value equal to "Basic " plus a base64 encoded representation of the user name, plus a colon, and password. Note the space following the word Basic. In the JavaScript code, we use the built-in DOM window.btoa(...) method to convert the value to base64.

Note

Basic is not allowed in Online, since all usernames and passwords must flow through SuperID to get a bearer access token.

SOTicket

Alternatively, if the HTML page is running in the context of a SuperOffice web panel, and the application passes in the user's SoCredential.Ticket, the REST request header also supports SOTicket, instead of Basic. In that case, the Authentication header value is "SOTicket " plus the ticket string. Once again, notice the space following SOTicket.

<script>
  _proj = {};

  function onGetId(f) {
    var urlbase = document.getElementById("url").value;

    var user = document.getElementById("user").value;
    var pass = document.getElementById("pass").value;

    var project = document.getElementById('projectid');
    var projectid = project.value;
    var url = urlbase + "/project/" + projectid;

    var req = new XMLHttpRequest();
    req.responseType = "json";
    req.open("GET", url, true);
    req.withCredentials = true;
    req.setRequestHeader("Authorization", "Basic " + btoa(user + ":" + pass))
    req.onload = function () { onGetProject(req.response); };
    req.onerror = function () { alert("Request Error - check Console for details."); };
    req.send();

    // Don't submit form
    return false;
  }

  function onGetProject(proj) {
    _proj = proj;

    var n = document.getElementById('project_name');
    var ti = document.getElementById('project_typeid');
    var tn = document.getElementById('project_typename');

    n.value = proj.Name;
    ti.value = proj.ProjectType.Id;
    tn.value = proj.ProjectType.Value;

    n.style.fontWeight = "normal";
    ti.style.fontWeight = "normal";
    tn.style.fontWeight = "normal";
  }

  function SaveProject() {
    var n = document.getElementById('project_name');
    var ti = document.getElementById('project_typeid');
    var tn = document.getElementById('project_typename');

    _proj.Name = n.value;
    _proj.ProjectType.Id = ti.value;
    _proj.ProjectType.Name = tn.value;

    var urlbase = document.getElementById("url").value;
    var user = document.getElementById("user").value;
    var pass = document.getElementById("pass").value;

    var project = document.getElementById('projectid');
    var projectid = project.value;
    var url = urlbase + "/project/" + projectid;

    var req = new XMLHttpRequest();
    req.responseType = "json";
    req.open("PUT", url, true);
    req.withCredentials = true;
    req.setRequestHeader("Authorization", "Basic " + btoa(user + ":" + pass));
    req.setRequestHeader("Content-Type", 'application/json');
    req.onload = function () { onSaveProject(req.response); };
    req.onerror = function () { alert("Request Error - check Console for details."); };
    req.send(JSON.stringify(_proj));

    return false;
  }

  function onSaveProject(proj) {
    _proj = proj;

    var n = document.getElementById('project_name');
    var ti = document.getElementById('project_typeid');
    var tn = document.getElementById('project_typename');

    n.value = proj.Name;
    ti.value = proj.ProjectType.Id;
    tn.value = proj.ProjectType.Value;

    n.style.fontWeight = "bold";
    ti.style.fontWeight = "bold";
    tn.style.fontWeight = "bold";
  }

</script>

Note

In this case, don't use the window.btos(...) method to convert a Ticket to base64 because the ticket value is already base64 encoded.