Introduction to Web Interfaces

Information

• A web interface defines the endpoint at which you can interact with PLANTA.
  • Web interfaces can be created and configured in the Web Interfaces module.
• You can store an implementation and a web entity for each method (GET, PUT, POST, DELETE).
  • The implementation defines the behavior of the interface when it is opened.
  • A web entity
    • describes the object which interacts with the web interfaces (e.g. the values returned by a GET request).
    • has a name and points to a data table.
    • has n web attributes, each pointing to a data item from the data table.
      • Web attributes have a name and optionally a transformer class which transforms the respective value.
    • can be created and configured in the Web Entities module.

Notes

• To be able to use web interfaces you have to activate and configure the PLANTA link webservices in the web.conf:
  • generic_service = true
  • generic_service_interface and generic_service_port contain meaningful data
• If you have not activated the webservices, the buttons for carrying out different actions which require webservices will not be displayed.
• Web interfaces use the Fully Qualified Domain Name (FQDN) as an address by default. If the FQDN is not available, the host name of the machine will be used. If the host name is not available either, the IP of the machine will be used. An explicit host name can be defined using the global planta_link_hostname setting.

All fields in the web interface modules are case sensitive (observe upper/lower case spelling)!

Methods

Behavior of the DefaultServiceImplementation class:

• GET
  • Data is retrieved from the database based on the configured web entity.
  • You can restrict the selection by using a URL filter.
  • The response contains a JSON formatted list of object representations with the values of the defined attributes of the web entity.
• PUT
  • Expects a json encoded dictionary in the body of the HTTP request the keys of which match the assigned web entity.
    • If an attribute is declared as mandatory field PUT and is missing in the request, the request fails with status code 400.
    • If there is an additional attribute in the request which does not exist in the web entity as an attribute, the request fails with status code 400 as well.
  • If the correct attributes are specified, the interface loads all lines from the data table of the web entity, restricted by the optional URL filter.
  • The respective data is updated with the transferred attributes of the request.
  • The response contains a JSON formatted list of object representations with the values of the defined attributes of the web entity.
• POST
  • Expects a json encoded dictionary in the body of the HTTP request the keys of which matches the assigned web entity.
    • If an attribute is declared as mandatory field POST and is missing in the request, the request fails with status code 400.
    • If there is an additional attribute in the request which does not exist in the web entity as an attribute, the request fails with status code 400 as well.
  • If you have specified the correct attributes, the interface creates a new record in the data table of the web entity.
  • The auto number DIs are filled automatically, regardless of whether they are specified as attributes in the web entity.
  • The transferred values are written in the respective columns.
  • In its body, the response contains a JSON object with the values of the defined attributes of the web entity.
• DELETE
  • Deletes all data from the table of the web entity, restricted by the optional URL filter.
  • The response body contains a JSON object which is structured as follows:
    • {'result': {'error': <List of undeleted object representations with the values of the defined attributes of the web Web Entity>, 'deleted': <List of deleted object representations with the values of the defined attributes of the web entity>}}

Error Treatment

Information

• If a web interface is deactivated (Active = @N), PLANTA project behaves as if the end point did not exist.
• Web interfaces have a generic error treatment function which allows for a consistent treatment of errors which occur in the processing of a request.
• In the request_headers attribute, the headers of the request are stored as a dictionary.
• If the transformation of attributes has failed in a PUT/POST request, an error message which shows the fields that could not be processed will be displayed.
• If mandatory fields are missing in a PUT/POST request or redundant fields are sent, an error message which indicates the respective fields will be displayed.