Expertsystemen

REST

For the creator of a model, the REST interface is not that interesting. You add some data to a definition, and get some information back. With the REST definition file, a more technical person can create the interface, so the model creator can focus on the content of that model.

REST definition file

The definition of a REST interface is made in a xml file, that starts with bbrest and has the extension .xml, for example bbrest.im.CompanyService.Address.xml. These files are stored in the subfolder restdef on the server. The same way, those files can be stored for the Editor. On startup, the program will search for those files, and offer the interfaces to the model.

The minimal content of an XML is as follows:

<?xml version="1.0" encoding="UTF-8"?>
  <bb:berkeleybridgerest xmlns:bb="www.berkeleybridge.nl/rest">
  <bb:url>https://server.com</bb:url>
  <bb:description>Get dossier</bb:description>
  <bb:method>GET</bb:method>
  <bb:resource>/api/versie</bb:resource>
  <bb:request/>
  <bb:requestelement>//bb:request</bb:requestelement>
  <bb:reply>
    <rootelement>
      <status/>
      <version/>
    </rootelement>
  </bb:reply>
  <bb:replyelement>//bb:reply</bb:replyelement>
</bb:berkeleybridgerest>

The description value is referenced in the Editor to recognize this API. This description is also used in the model. The server needs to have access that same file, or a copy of that file. The requestelement and replyelement point (xpath) to the element where the request and element will be defined.

It needs the URL and RESOURCE to execute the request. This can be GET, POST, PUT, DELETE described in METHOD. The request and reply will be described in JSON translated to XML. In case of JSON not having a rootelement, one is added. In this example the server does not expect anything except a GET request on https://serverv.com/api/versie and it will reply in JSON

{
  "status": "succes",
  "version": "42.22.34"
}

You can use VALUE in de bbrest definitions. Then there will be just a value (as answer or request). E.g. answer is 23. Just keep an empty element <bb:reply> or <bb:request> and connect that in the model.

Quotes

The URL or RESOURCE can be dynamic. We use quotes to do this. Also the header of a request can be manipulated using quotes.

A quote is the reference to a value in an element, using a ^{name} construct, e.g. <bb:resource>/api/v1/matters/^{matter_id}/export</bb:resource>

The value of matterid is given by the list in <bb:restparameter>.

In the root you can add the bb:restparameter which can contain as many parameters as you want.

  <bb:restparameter>
    <bb:parameter>matter_id</bb:parameter>
  </bb:restparameter>

The value of matter_id can be set from the model. This is explained in the last chapter of this document.

API parameters

Header parameters

The API request contains headers You can add the element bb:requestheader to the root element bb:berkeleybridgerest. In that element you can put as many bb:parameter elements as you want. These elements can contain just a value, or quote a value from the model. There are special values used outside the model. In this example the header value Authorization is added, with the value Bearer oauth2:AccesToken. This value is from the oauth2 connection, which can be used accessing a model

<bb:requestheader>
  <bb:parameter name="Accept-Encoding">gzip, deflate, br</bb:parameter>
  <bb:parameter name="token">^{token}</bb:parameter>
  <bb:parameter name="Authorization">Bearer ^{oauth2:AccesToken}</bb:parameter>
</bb:requestheader>

Url parameters

Sometimes you need parameters in the resource as well. (the ?q=32&u=ret at the end of a resource) This can be accomplished by the parameter list in bb:requestparameter.

  <bb:requestparameter>
    <bb:parameter name="q">^{query}</bb:parameter>

Body parameters

The body of a request can contain parameters as well. For example, if you want to send a file.

<bb:requestbody>
  <bb:parameter name="profile">^{profile}</bb:parameter>
  <bb:parameter type="rawfile" name="file">^{file}</bb:parameter>
  <bb:parameter name="file">^{file}</bb:parameter>
  <bb:parameter type="raw" name="content">^{content}</bb:parameter>
</bb:requestbody>

If there is no type, the content will be added to the body. The value will be URLEncoded. If you do not want this, use type="raw". Adding type="file" means the file will be added. Rawfile indicates that the file will be added as text. The file variable in this example must point to the relevant document created by the model.

If you add a node ‘cookiedata’ to the communication dataset, the name-value in the optional cookies will be set in the corresponding data. In this example there are two cookies with the value LB_STICKY and SESSION. The checking of the name is case-insensitive. This only works for the native REST api, not INDY.

 node cookiedata;
 var
   lb_sticky,
   session;
 begin
   lb_sticky := '';
   session := '';
 end;

BBREST elements

In the bbrest XML there are extra elements one can add to change the behavior of the REST API.

IndySocket

<bb:useindysocket>Boolean</bb:useindysocket>

true if indysocket is needed. This socket is only needed for two-way-ssl. Indysocket is false is the default and the preferred. The non-indy socket is the Windows TCP socket, the indy socket uses openSSL.

Two way SSL

<bb:authtype rootcertfile="root.crt" certfile="clnt.crt" keyfile="SSL\clnt.key">twowayssl</bb:authtype>

You can set authtype with the value twowayssl. You must have useindysocket on true. The files are relative to the executable (e.g. bbwebservice.exe).

Authentication

<bb:authentication>true</bb:authentication>

If you want to use basic authentication, set this value to true, and add the following elements to bb:berkeleybridgerest

<bb:username>x</bb:username>`
<bb:password>x</bb:password>

Force boolean values

<bb:forceboolean>true</bb:forceboolean>

All values in the xml to json are converted to strings. If this value is set, the xml values true and false are set as boolean in the JSON file.

Use a proxy

<bb:proxy port="8080" username=”x” password=”x”>10.48.208.166</bb:proxy>

Use this element to set a proxyserver. The username and password are optional.

Contenttype value

<bb:contenttype>application/json</bb:contenttype>

If you want to change the standard contenttype.

Accept value

<bb:accept> application/json, text/plain; q=0.9, text/html;q=0.8,</bb:accept>

If you want to change the accept value

The request content

<bb:requestcontent>XML</bb:requestcontent>

The content of a request can be XML or JSON or VALUE. Default is JSON

The response content

<bb:responsecontent>XML</bb:responsecontent>

The content of a response can be XML or JSON or VALUE. Default is JSON

Remove Request Rootelement

<bb:removerequestrootelement>true</bb:removerequestrootelement>

A request can be a JSON with no root element. In the XML definition you must use that rootelement. If you want to remove that in the request, just set this element to true.

Processing instruction translate

<bb:processing-instruction 
    jsonname="continuation Context"
    xmlname="continuationContext">translate</bb:processing-instruction>

You can give translate elements between JSON and XML. XML is much more stringent, for example, spaces are not allowed. With translate you can overcome these differences.

Processing instruction escapejson

<bb:processing-instruction xpath="rootelement/contract">escapejson</bb:processing-instruction>

You can remove elements, and shift the content to the higher element.

Processing instruction transform

If you use xml in the response or request, you can use

<bb:processing-instruction transform="request">transform.xsl</bb:processing-instruction>

and/or

<bb:processing-instruction transform="response">transform.xsl</bb:processing-instruction>

If you use JSON in the response or request, you can use

<bb:processing-instruction transformq="request">transform.jq</bb:processing-instruction>