Restfull API description

Conventions

Administrator functionnalities

Some functionnalities are restricted to users with adminiatror rights. alogin/password is therefore required to access them. Such functionnalities are decribed in this documentation with the mention [Admin].

DELETE and PUT methods

Note that if you want to use the REST interface with a web navigator (IE, Firefox,...), it is not possible to execute DELETE or PUT methods for somes operations. In that case, it is recommended to use a POST request with the parameter _method containing the name of the real HTTP method to use.

Some conventions

In this document, texts between {} signs are to be replaced with the appropiate value

Text to be replaced by

{id_action} Id for alert action

{id_job} id for a job

{id_query} id for a query

{name_job} name of the job

{name_query} name of the query

{URL_Job} URL of a given job. Correspond to {URL_Monitor}/jobs/{id_job} or {URL_Monitor}/jobs/{name_job}

{URL_Job_or_Query} job or query URL depending of what is be be proceeded. Correspond to {URL_Job} or {URL_Query}

{URL_Monitor} application URL. Example : http://myserver:8080/Monitor

{URL_Query} given query URL. Correspond to {URL_Job}/queries/{id_query} or {URL_Job}/queries/{name_query}

Setting jobs

A job is defined for un given webservice and contains common information for all queries (see chapter "Query") and parameters for automatic execution, public access, errors management,etc.

Default parameters

Some job parameters have default values which are sistematically used when a new job is created. Default values are :

  • Parameter | Description -> Default value
  • allowsRealTime |Can the job be executed on demand (real-time) ?-> true
  • bizErrors | Should the job detect business errors (means OGC errors) ?-> true
  • httpErrors | Should the job detect HTTP errors (error 404,...) ?-> true
  • isAutomatic | Is the job running automatically ?-> false
  • isPublic | Is the job queryable by public users (not admin) ? -> false. If isPublic is set to true, the job goes on the "jobs" collection otherwise on the adminJobs collection.
  • slaEndTime | Service Level Agreement end-time ->18:00:00
  • slaStartTime | Service Level Agreement start time -> 08:00:00
  • testInterval | Interval in seconds between to automatic execution (ignored if isAutomatic set to false)-> 3600
  • timeout | Delay of response in seconds -> 30
  • triggersAlerts | Does the job trigger alerts on status change ? -> false

[Admin] Interrogation

To get current default values, write a GET request on the URL {URL_Monitor}/jobDefaults.

[Admin] Setting

Setting of one or more default parameters are done with a PUT request on the URL {URL_Monitor}/jobDefaults.
Ones should specify the parameter and the value to be changed.

Existing jobs

[Admin] List of all jobs

A GET request on job admin collection ({URL_Monitor}/adminJobs) will return all informations about existing job. Request on specific jobs is possible with the following parameters :

  • Parameter | Description -> Value
  • allowsRealTime | Can the job be executed on demand (real-time) ?-> (true/false)
  • isAutomatic | Is the job running automatically ?-> (true/false)
  • isPublic | Is the job queryable by public users (not admin) ? -> (true/false)
  • triggersAlerts | Does the job trigger alerts on status change ? -> (true/false)

Public jobs list

Users with no specific admin rights can request public job list with a GET on the ressource {URL_Monitor}/jobs.

[Admin] Create a job

Execute a POST request on jobs collection {URL_Monitor}/jobs. Required parameters are :

  • Parameter | Value
  • httpMethod | HTTP method to request the service (GET ou POST)
  • name | name of the job
  • serviceType | OGC service type (CSW, SOS, WFS, WMS, WMTS)
  • url | webservice URL

Optionnal parameters are (MONITOR take default values if no others are specified):

  • Parameter | Value
  • allowsRealTime | Can the job be executed on demand (real-time) ?-> (true/false)
  • bizErrors | Should the job detect business errors (means OGC errors) ?->(true/false)
  • httpErrors | Should the job detect HTTP errors (error 404,...) ?-> (true/false)
  • isAutomatic | Is the job running automatically ?->(true/false)
  • isPublic | Le job est-il consultable par les utilisateurs publics ? (true/false)
  • login | login to connect for http authentification
  • password | password for http authentification
  • slaEndTime | Service Level Agreement end-time ->(hh:mm:ss)
  • slaStartTime | Service Level Agreement start-time ->(hh:mm:ss)
  • testInterval | Interval in seconds between to automatic execution (ignored if isAutomatic set to false)
  • timeout | Delay of response in seconds
  • triggersAlerts | Does the job trigger alerts on status change ? -> (true/false)

Visualize a job

A GET request on job URL ({URL_Monitor}/jobs/{id_job} or {URL_Monitor}/jobs/{name_job}) will return all job parameters.

Execute a job

If real-time job is allowed (allowsRealTime true), a GET request on {URL_Monitor}/jobs/{id_job}/status or {URL_Monitor}/jobs/{name_job}/status will return the status of the job. No logs are saved. No alerts triggered.

Note : if the job is not public, only Admin can use this method.

[Admin] Modify a job

A PUT request on the given job ({URL_Monitor}/jobs/{id_job} or {URL_Monitor}/jobs/{name_job}) with parameters to be changed with corresponding values will update the job. Parameters that are not mentioned will not be changed.
Please note that if a query is already assigned to a job, the parameter serviceType remains read-only.

[Admin] Delete a job

A DELETE request on a given job ({URL_Monitor}/jobs/{id_job} or {URL_Monitor}/jobs/{name_job}) will delete the job.

Alerts and actions

If the triggersAlerts parameter is activated for a given job, an alert is triggered when job status is changed on automatic mode.

List of alerts

A GET request on a job ({URL_Job}/alerts) will return the list of alerts saved for this job

Feed RSS

TO DO

Actions

When an alert is triggered, actions can be defined :

1. send an email
2. feed an RSS

[Admin] Action definition

A POST resquest can be done on a action collection for a given job ({URL_Job}/actions). Parameters are :

  • Parameter | Value
  • Lang |ISO 639-1 code of the language that will be used for the action. For an E-MAIL action, if the language is not managed or the parameter omitted, the default one will be used. For RSS action, the language is defined the the RSS reader.
  • Target | List of email adresses separated by ";". No value for RSS action.
  • Type | Action type (E-MAIL or RSS)

[Admin] List of job actions

A GET request on jobs collection ({URL_Job}/actions) will return the list of actions for the given job.

[Admin] Visualize an action

A GET request on ({URL_Job}/actions) will return the paramters of a given action.

[Admin] Change an action

A PUT request on ({URL_Job}/actions/{id_action}) with specified parameters will modify the given action.

[Admin] Delete an action

A DELETE request on ({URL_Job}/actions/{id_action}) will delete the given action.

Automatic tasks

Automatic execution of jobs and aggregation of logs are carried through scheduled tasks. However, they can only take place when the MONITOR application is running. In case of interruption (server down for example), these tasks are rescheduled, then executed when the MONITOR is running again.

Message languages

MONITOR supports localization of alert messages. Specifying the language to be used can be done by :
  • Accept-Language header in the HTTP request (automatic for most of the web browser)
  • add parameter "_lang_" in the request. Values are based on ISO code (Example : lang=fr for french)

If you want another language than the default one, the paramater lang should be added in each request.

Note : only french and english languages are supported in localization file of MONITOR. In case of others langagues, the default language will be used. Or you should add other translations in the localization file.

MONITOR.eap - Use case Diagram MONITOR (2.11 MB) Portier Thomas, 04/07/2014 06:00 PM

EasySDI-Monitor-Business-Class-Diagramm.xls - Business Class diagramm (23 KB) Portier Thomas, 04/07/2014 06:00 PM