Web Services BETA

Notes

• The web service interface is in its beta stage.
• The productive use is therefore not approved.

Why Web Services?

Information

• The web service interface serves to enable access to the PLANTA Server.
• This way, data can be offered to different external systems.
  • So far, access to PLANTA data has only been possible via file export or direct database access.
  • The file access often causes buggy copying between systems.
  • In direct database access you can only access the raw data. Field calculations or aggregations must be duplicated.
• It also serves to implement administrative todo items and monitoring mechanisms, which facilitates the embedding of the PLANTA server in the existing IT environment.

Activation and Configuration

Procedure

Furthermore individual services can be (de)activated.

• In the delivery status, all services are activated, provided that the web services are switched on globally.
• The web-inf/implementation/services/framework/registration.py Python module can be edited in the server directory.
• For each service to be activated, a configuration is created as follows:

    exampleConfig = WebServiceConfiguration('example', 'v1', 'de.planta.webservice.jaxrs.api.v1.ExampleApi')
    exampleConfig.setImplementationPath('services.planta.example.ExampleApi')

• • The configurations must then be returned by the get_registered_services() function.
  • Below, you see the function in delivery status:

from de.planta.webservice import WebServiceConfiguration

def get_registered_services():
    tasksConfig = WebServiceConfiguration('tasks', 'v1', 'de.planta.webservice.jaxrs.api.v1.TasksApi')
    tasksConfig.setImplementationPath('services.planta.webclient.tasks.TasksApi')

    sessionConfig = WebServiceConfiguration('sessions', 'v1', 'de.planta.webservice.jaxrs.api.v1.SessionsApi')
    sessionConfig.setImplementationPath('services.planta.webclient.sessions.SessionsApi')

    monitoringConfig = WebServiceConfiguration('monitoring', 'v1', 'de.planta.webservice.jaxrs.api.v1.MonitoringApi')
    monitoringConfig.setImplementationPath('services.planta.webclient.monitoring.MonitoringApi')

    return [tasksConfig, sessionConfig, monitoringConfig]

Use

Details

• The web services are designed as REMAINING interfaces.
• Upon use, a HTTP client is used to support the HTTP methods GET, POST, PUT, and DELETE.
  • The curl command line tool can be used for example.
  • External applications (like monitoring frameworks) often enable the HTTP access via a configuration of the end point.
• The web service interface is delivered with an interactive web based documentation of the existing services.
  • This documentation includes all available end points with obligatory as well as optional parameters.
  • Furthermore, the documentation describes the format of the expected return values and error codes.
  • As far as the respetive services are activated, they can be addressed via the documentation application.

Safety Aspects

Notes

• Access to module variants is secured via the API keys.
• They must be sent in plain text in the HTTP header. Therefore a connection secured by means of TLS is required to secure the services.
• Since there is no respective infrastructure implemented in the PLANTA server, external components like stunnel or NginX must be used for the backup.
• You can configure individual keys for each service.
• For this purpose, the web-inf/implementation/services/framework/authentication.py Python module must be edited.
  • Each service receives an entry with a list of keys via which access is possible in the apiKeys directory.

apiKeys = {
    "sessions": ["sessionskey", "sessionskey2"],
    "tasks": ["taskskey", "taskskey2"]
}

Delivered Services

Information

• Since all delivered services are described via the documentation application, you will only find a brief description for each service here.

Session Service

Information

• The session service is responsible for the administration of sessions.
• All sessions launched since PLANTA was started can be viewed here.
• The sessions can be filtered by different criteria (e.g. status).
• Furthermore active sessions can be terminated.

Monitoring Service

Information

• Via the monitoring service, the PLANTA server can be monitored.
• For this purpose, you can query different system properties and the status.

Task Service

Information

• The task service enables query and modification of particular task properties.
• Serving merely as a representative technical demonstration of data based services, the implementation is restricted to a demo data project.