The Blawx Web API

Controlling Access to the Web API

By default, when you create a project in Blawx, that project is "unpublished". This means that the project can be viewed and used only by the user that created it. The contents of the project are also accessible to server admins.

If you go into the Rule Editor from your Project, you can set your project to "Published". Doing so gives anonymous users access to view and execute your code, but not to modify it. If you want your code to be usable in BlawxBot for un-authenticated users, you must set your project to Published in the Rule Editor screen.

API Endpoints

There are three endpoints available for each test defined in your Blawx project:

  • The "Run" Endpoint
  • The "Ontology" Endpoint
  • The "Interview" Endpoint

One additional endpoint is available for each Project in Blawx:

  • The "Rule" Endpoint

The Run Endpoint

The run endpoint is the endpoint used by the test editor when you click "Run".

It returns a JSON object which is a dictionary containing two keys, "Answers" and "Transcript".

Both are in the same format as described below for the Interview endpoint.

The Run endpoint can be obtained by adding /run to the end of the URL displayed when in the test editor, and if you go to that address in your browser, you will see a web interface to allow you to specify JSON inputs and review the responses. The endpoint accepts only POST requests.

The "Ontology" Endpoint

The ontology endpoint is available at the address obtained by adding /onto to the end of the URL displayed when in the test editor. If you go to that address in your browser, you will see a web interface to allow you to specify JSON inputs and review responses. The endpoint accepts only GET requests.

The response is a JSON object which is a dictionary, the keys of which are "Categories", "CategoryNLG", "Attributes", "AttributeNLG", "Objects", "Values", and "Transcript".

"Transcript" is in the format described below for the interview endpoint.

"Categories" is a list of category names.

"CategoryNLG" is a list of dictionaries, each of which has the keys "Category", "Prefix" and "Postfix", describing the details provided in a category declaration block.

"Attributes" is a list of dictionaries, each of which has the keys "Category", "Attribute", and "Type". The Category is the name of the category for which the attribute is defined. The Attribute is the name given to the attribute. The Type is the type specified, which will either be the name of a category, or one of "boolean", "number", "date", "time", "datetime", or "duration".

"AttributeNLG" is a list of dictionaries, each of which has the keys "Attribute", "Order", "Prefix", "Infix" and "Postfix", describing the details provided in an attribute declaration block. Order will be either "vo" or "ov", indicating the order in which the object and the value appear in the natural language expression.

"Relationships" is a list of dictionaries, each of which has the key "Relationship", and between 3 and 10 keys "ParameterN" where N is replaced with the number of the parameter. The "Relationship" is the name of the relationship. Inside each "ParameterN" key is the data type or category for that parameter in the relationship. The available types are the same as for attributes.

"RelationshipNLG" is a list of dictionaries, each of which has the keys "Relationship", "Postfix", and between 3 and 10 "PrefixN" keys where N is replaced with the number of the parameter. The relationship key is the name of the relationship, the PrefixN keys hold text that should appear before each of the parameters in the relationship, and the Postfix key holds text that should appear after all parameters.

"Objects" is a list of dictionaries, each with the keys "Category" and "Object", describing the category and the name of the object in that category.

"Values" is a list of dictionaries, each with the keys "Object", "Attribute", and "Value", describing a known value for that object and attribute.

"Relations" is a list of dictionaries, each with the keys "Relationship", and a set of 3 to 10 keys named "ParameterN" where N is replaced with the number of the parameter, describing a known statement for that relationship.

The ontology endpoint is intended to be used at the start of an interaction between Blawx and another application, to provide the other application with information about what data structure is used in the encoding, and to provide hints about how to collect items into that data structure.

The "Interview" Endpoint

The interview endpoint is available at the address obtained by adding /interview to the end of the URL displayed when in the test editor. If you go to that address in your browser, you will see a web interface to allow you to specify JSON inputs and review responses. The endpoint accepts only POST requests.

This endpoint expects a data payload in the following format:

The JSON is a dictionary with a single key, "facts", the value of which is a list of statements.

A statement is a dictionary with:

  • A 'from_ontology' key, the value of which is a true or false value. This is used to note which facts were already present in the code and were not provided by the user. Data provided by a user application should always set the 'from_ontology' value to false.
  • A 'type' key, the values of which can be the strings 'true','false', or 'unknown'.
  • Either a 'category', 'attribute', or 'relationship' key, where the value is the name of the category or attribute or relationship about which a statement is being made.
  • For categories and attributes only, an 'object' key, the value of which is either the name of an object as a string, or a variable definition (described below).
  • In the case of non-boolean attributes, a 'value' key, the value of which is the particular value being provided, or a variable definition (described below).
  • For relationships, a set of between 3 and 10 "parameterN" keys where N is replaced with the parameter number, setting out the value or variable definition for each.

Dates, datetimes, times, and durations are provided as strings in ISO8601 format. Numbers and booleans are provided in the standard JSON format.

{ 'facts': [
    { 'from_ontology': false,
      'type': 'true',
      'attribute': 'birthdate',
      'object': 'bob',
      'value': '1996-05-14'
    },
    { 'from_ontology': false,
      'type': 'true',
      'attribute': 'arrival',
      'object': 'bob',
      'value': '1996-05-14T12:23:49'
    },
    { 'from_ontology': false,
      'type': 'true',
      'attribute': 'appointment_time',
      'object': 'bob',
      'value': '15:45'
    },
    { 'from_ontology': false,
      'type': 'true',
      'attribute': 'duration',
      'object': 'bob',
      'value': 'P1Y5MT5H30S'
    },
    { 'from_ontology': flase,
      'type': 'true',
      'relationship': 'trio',
      'parameter1': 'bob',
      'parameter2': 'jane',
      'parameter3': 'terry'}
  ]
}

A variable is a dictionary with a single key, 'variable', the value of which is any string. Using a variable in the place of an object or a category-type value makes that term unground, in the logic programming sense. The only function of the string is to determine whether the same string has been provided in both the object and value of the statement, allowing Blawx to distinguish the unground statement "everyone knows themselves", which might appear like this:

{ 'facts': [
    { 'from_ontology': false,
      'type': 'true',
      'attribute': 'knows',
      'object': {'variable': 'one'},
      'value': {'variable': 'one'}
    }
  ]
}

from the statement "everyone knows everyone", which would appear like this:

{ 'facts': [
    { 'from_ontology': false,
      'type': 'true',
      'attribute': 'knows',
      'object': {'variable': 'one'},
      'value': {'variable': 'two'}
    }
  ]
}

Variable names are not case sensitive. The variable "one" and "One" will be treated as though they are identical.

Additional examples can be obtained by using the Scenario Editor to run a test, and then looking at the "Devel" tab, which will show the JSON package that was delivered to the interview endpoint, and the response.

The output from the interview endpoint is a JSON dictionary with keys "Answers", "Relevant Statements", and "Transcript".

"Answers" is a list of answers, which will be empty if the same question would have returned "no models" in the test editor. An Answer is a dictionary with keys "Variables", and "Models". "Variables" is a dictionary of variable names used in the question, and the values bound to that variable name in the current answer. "Models" is a list of dictionaries with keys "Tree", and "Terms", "Residuals" and "Raw". "Tree" is a list of nested lists providing the text value of the explanation displayed to the user in the output pane of the Test Editor. Section names are not resolved in this data. "Terms" is a list of terms that held in that model, in the same format as is used in the "Raw" data. "Residuals" are in the same format and represent constraints that have been applied to the unground elements of the explanation. "Raw" is the JSON representation of the raw form of a justification returned by the s(CASP) library in SWI-Prolog.

"Relevant Statements" is a list of statements in the same format as for "Terms" which sets out the statements which were abduced in the current model. If you use the "unknown" feature to describe questions that have not yet been posed to a user, the "Relevant Statements" list can be used to pose only relevant questions to the user.

"Transcript" is a string showing the data that was returned from the SWI-Prolog reasoner while executing the web API request, and is used primarily for debugging problems with Blawx, and Blawx encodings.

The "Rule" Endpoint

The Rule endpoint is available at the address obtained by adding /rule/{section_id} to the end of the address shown when you are in the Project page for a given project. Section ids are the section identifies generated by Blawx on the basis of the Project's legal text, and correspond to the eId attribute value generated in the corresponding Akoma Ntoso version of the legislation, displayed at the bottom of the Project page.

The format of a section_id will be something like one of the following:

  • sec_1
  • sec_1__subsec_2
  • sec_1__subsec_2__para_a
  • sec_1__subsec_2__para_a__subpara_i
  • sec_1__para_a
  • sec_1__para_a__subpara_i__span_spanname
  • etc...

The endpoint accepts only GET requests, and returns a JSON dictionary with keys "xml" and "text". The value of the text key is the Akoma Ntoso code for that section and its sub-components. The value of the text entry is a plain-text representation of the content of that section of the law.