About

The 52°North WPS 2.0 REST API for TAMIS provides a thin access layer to processing functionalities for timeseries data via RESTful Web binding.

This API development intends to make processing services (provided by OGC Web Processing Services (WPS)) better accessible for leightweight clients like mobile devices.

As a specific REST API for the 52°North BMBF TAMIS Project, the main goal of this REST API is to downsize the content of exchanged messages. For this reason, in contrast to the full request/response structures declared in the official OGC WPS 2.0 Interface Standard, the contents of each request and response are reduced to a minimum. Additionally, it provides processing functionalities for timeseries data retrieved by an OGC Sensor Observation Service (SOS) via the 52°North Series REST API.

Document status

What When
Initial creation 2016-08-09
Made several changes:
  • more explanation on TAMIS project specific features. Add comparison notes that show how the TAMIS REST interface differs from official OGC WPS spec.
  • Add Content Types section
  • In particular, the Execute section has been revised and extended with explanations of request/response encodings.
  • minor text tweaks
  • correct false explanation of base-url
  • add section Architecture and Role of TAMIS REST
  • add notes on how Series REST API is utilized to retrieve timeseries data for process execution
2016-08-11

Architecture and Role of TAMIS REST Component

architecture figure

From a developer's perspective, the TAMIS REST API is implemented as a proxy component as shown in the previous figure. Clients access the TAMIS WPS REST Proxy via REST URLs explained in this document. The TAMIS WPS REST Proxy then accesses another Generic WPS REST Proxy that provides a 1:1 REST interface for the 52°North Web Processing Service (1:1 means, that requests and responses are encoded in application/json but have the same structure as typical XML requests and -responses!).

Developer Note: to configure the Generic WPS REST Proxy endpoint URL, change the property wpsProxy_baseUrl in the file wpsProxy-properties located at the project folder tamis-rest-api/webapp/src/main/resources/wpsProxy.properties.

The role of the TAMIS WPS REST Proxy is to simplify request/response structures and, thus, reduce message contents to a minimum and ease communication with clients. How this simplification affects each operation of a WPS is explained in each corresponding subsection.

In addition, the TAMIS WPS REST Proxy offers processing functionalities for timeseries data, which is stored in a SOS. To retrieve timeseries data the TAMIS WPS REST Proxy uses the 52°North Series REST API. Section Process Execution explains this functionality in more detail.

Content-Types

The content type for message exchange is application/json . It is set as the default content type but can be set via HTTP header.

Nearly each operation request is fully formulated through a REST URL alone without request payload. Only the Execute Operation requires the definition of process in- and outputs via a request payload encoded in application/json.
Nearly each operation response is also encoded in application/json. However there is one exception: Asynchronous Execute operation returns only a Location header containing a link to the corresponding Status Info document.

Common Status Codes

A client shall expect the following HTTP status codes returned by the API.

Code When
200 Status OK. All went fine.
201 Status Created. New job (process execution) created.
400 Status Bad Request. The request data cannot be read.
404 Status Not Found. The resource is not available. In particular, when trying to dismiss an existing job more than once, this status is returned.
415 Status Unsupported Media Type. The media-type of the request payload is not supported. Prevent this error by setting the Content-Type header to application/json.
500 Status Internal Server Error. Please contact the webadmin. In some cases an error message will be shown. But in general the server logs will help to trace the problem.

Endpoint URL

The entry point of the REST API will be referenced as the <base-url> throughout the rest of this document. The <base-url> consists of the TAMIS WPS REST Proxy endpoint and a static suffix /api/v1/service/{service-id} whereby {service-id} is a variable to differentiate between mutliple WPS instances.

Currently, the {service-id} is simply set to 1. There is no support for multiple instances yet! The TAMIS WPS REST Proxy is configured to access the generic WPS REST Proxy as described in section Architecture and Role of TAMIS REST component.

For instance, a valid endpoint is provided by the following enpoint URL: http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET <base-url> application/json Lists Capabilities of the WPS.

Examples

Capabilities Response

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/ HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "1",
  "label": "52°North WPS 4.0.0-SNAPSHOT",
  "type": "WPS",
  "url": "http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/",
  "contact": "Benjamin Pross"
}
Note that in contrast to a full Capabilities response, as specified in the formal OGC WPS Interface Standard - GetCapabilities Response Section, the response of the WPS 2.0 TAMIS REST Interface is reduced dramatically. Nearly all meta-information (service identification, service provider, operations metadata, languages, list of process summaries) is omitted. A list of available processes can be retrieved through the Processes operation instead.
The returned Capabilities document contains a parameter url that points to the TAMIS REST API endpoint of the service instance.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET <base-url>/processes application/json Lists the available processes of the WPS.

Examples

Processes Example

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/ HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "org.n52.wps.server.r.tamis-regression",
    "label": "Interpolation of Wasserstand at Bevertalsperre",
    "description": "Interpolation of Wasserstand at Bevertalsperre",
    "url": "http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-interpolation"
  },
  {
    "id": "org.n52.wps.server.r.tamis-regression",
    "label": "TaMIS Regression Model for Wasserstand_im_Damm or Schuettmenge at Bever-Talsperre",
    "description": "TaMIS Regression Model for Wasserstand_im_Damm or Schuettmenge at Bever-Talsperre",
    "url": "http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression"
  }
]
Note that in contrast to a full process summary of a Capabilities response, as specified in the formal OGC WPS Interface Standard - GetCapabilities Response Section the Processes response of the WPS 2.0 TAMIS REST Interface is reduced to id, label (which is used instead of formal Title property) and description (which is used instead of formal Abstract property). The remaining information (version, keywords, metadata, process model, job control options, output transmission) is omitted.
Each encoded process is enriched with a parameter url that represents the TAMIS REST API call to obtain the corresponding Process Description.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET <baseURL>/processes/{process-id} application/json Returns the process description for the process with the specified id {process-id}.

Examples

Process Description Example

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "org.n52.wps.server.r.tamis-regression",
  "label": "TaMIS Regression Model for Wasserstand_im_Damm or Schuettmenge at Bever-Talsperre",
  "description": "TaMIS Regression Model for Wasserstand_im_Damm or Schuettmenge at Bever-Talsperre",
  "inputs": [
    {
      "id": "sosInputNiederschlag",
      "label": "SOS-request",
      "type": "text/plain | text/xml",
      "required": false
    },
    {
      "id": "sosInputFuellstand",
      "label": "SOS-request",
      "type": "text/plain | text/xml",
      "required": false
    },
    {
      "id": "sosInputTarget",
      "label": "SOS-request",
      "type": "text/plain | text/xml",
      "required": false
    },
    {
      "id": "sosInputNiederschlagPred",
      "label": "SOS-request",
      "type": "text/plain | text/xml",
      "required": false
    },
    {
      "id": "sosInputFuellstandPred",
      "label": "SOS-request",
      "type": "text/plain | text/xml",
      "required": false
    },
    {
      "id": "singleInputNiederschlagPred",
      "label": "single value",
      "type": "text/plain | text/xml",
      "required": false
    },
    {
      "id": "singleInputFuellstandPred",
      "label": "single value",
      "type": "text/plain | text/xml",
      "required": false
    }
  ],
  "outputs": [
    {
      "id": "targetObs_plot",
      "label": "targetObs_plot",
      "type": "image/png | image/png"
    },
    {
      "id": "model_diagnostics",
      "label": "model_diagnostics",
      "type": "image/png | image/png"
    },
    {
      "id": "relations",
      "label": "relations",
      "type": "image/png | image/png"
    },
    {
      "id": "model_prediction",
      "label": "model_prediction",
      "type": "text/csv | text/csv"
    },
    {
      "id": "metaJson",
      "label": "metaJson",
      "type": "application/json | application/json"
    },
    {
      "id": "dataJson",
      "label": "dataJson",
      "type": "application/json | application/json"
    },
    {
      "id": "sessionInfo",
      "label": "Information about the R session which has been used",
      "type": "text/plain"
    },
    {
      "id": "warnings",
      "label": "Warnings from R",
      "type": "text/plain"
    }
  ]
}
Note that in contrast to a full DescribeProcess response, as specified in the formal OGC WPS Interface Standard - DescribeProcess Response Section, the response of the WPS 2.0 TAMIS REST Interface is reduced to id, label (which is used instead of formal Title property), description (which is used instead of formal Abstract property) and arrays of inputs and outputs of the process. The remaining information (version, keywords, metadata, process model, job control options, output transmission) is omitted.
Also note, that the description of each input and output is reduced to id, label (which is used instead of formal Title property) and type (which represents available MimeTypes).

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
POST <base-url>/processes/{process-id}?sync-execute=false application/json

Creates a new job for process with specified id {process-id} and executes it ASYNCHRONOUSLY (request parameter sync-execute=false is equivalent to mode=async as specified in the OGC WPS Interface Standard - Execute Request Section).

Consequentially, the response will be HTTP status 201, containing a Location header pointing to the Status Info document.

POST <base-url>/processes/{process-id}?sync-execute=true application/json

Creates a new job for process with specified id {process-id} and executes it SYNCHRONOUSLY (request parameter sync-execute=true is equivalent to mode=sync as specified in the OGC WPS Interface Standard - Execute Request Section).

Consequentially, after the job has completely finished, the response will be a Result document, containing the computed results.

The query parameter sync-execute may be omitted. Then sync-execute=false (equivalent to mode=async as specified in the OGC WPS Interface Standard - Execute Request Section) is used per default.

POST Payload

Since the execute operation is done via HTTP POST, a proper Execute Request Payload has to be specified! Note that you should set the header Content-Type: application/json in the request. Otherwise the WPS might reject the request with an HTTP status 415 - Unsupported Media Type.


Exemplar Execute Request Payload

Content-Type: application/json;

{
    "inputs": [
        {
            "id": "sosInputNiederschlag",
            "value": "http://www.fluggs.de/sos2/sos?service%3DSOS&version%3D2.0.0&request%3DGetObservation&responseformat%3Dhttp://www.opengis.net/om/2.0&observedProperty%3DNiederschlagshoehe&procedure%3DTagessumme&featureOfInterest%3DBever-Talsperre&&namespaces%3Dxmlns%28sams%2Chttp%3A%2F%2Fwww.opengis.net%2FsamplingSpatial%2F2.0%29%2Cxmlns%28om%2Chttp%3A%2F%2Fwww.opengis.net%2Fom%2F2.0%29&temporalFilter%3Dom%3AphenomenonTime%2C2016-01-01T10:00:00.00Z%2F2016-04-30T23:59:00.000Z",
			"type" : "text/plain"
        },
        {
            "id": "sosInputFuellstand",
            "value": "http://www.fluggs.de/sos2/sos?service%3DSOS&version%3D2.0.0&request%3DGetObservation&responseformat%3Dhttp://www.opengis.net/om/2.0&observedProperty%3DSpeicherfuellstand&procedure%3DEinzelwert&featureOfInterest%3DBever-Talsperre_Windenhaus&namespaces%3Dxmlns%28sams%2Chttp%3A%2F%2Fwww.opengis.net%2FsamplingSpatial%2F2.0%29%2Cxmlns%28om%2Chttp%3A%2F%2Fwww.opengis.net%2Fom%2F2.0%29&temporalFilter%3Dom%3AphenomenonTime%2C2016-01-01T10:00:00.00Z%2F2016-04-30T23:59:00.000Z",
			"type" : "text/plain"
        },
        {
            "id": "sosInputTarget",
            "value": "http://fluggs.wupperverband.de/sos2-tamis/service?service%3DSOS&version%3D2.0.0&request%3DGetObservation&responseformat%3Dhttp://www.opengis.net/om/2.0&observedProperty%3DWasserstand_im_Damm&procedure%3DHandeingabe&featureOfInterest%3DBever-Talsperre_MQA7_Piezometer_Kalkzone&namespaces%3Dxmlns%28sams%2Chttp%3A%2F%2Fwww.opengis.net%2FsamplingSpati-al%2F2.0%29%2Cxmlns%28om%2Chttp%3A%2F%2Fwww.opengis.net%2Fom%2F2.0%29&temporalFilter%3Dom%3AphenomenonTime%2C2016-01-01T00:01:00.00Z%2F2016-04-30T23:59:00.000Z",
			"type" : "text/plain"
        }
    ],
    "outputs": [
      {
              "id": "targetObs_plot",
              "type": "image/png"
       },
      {
              "id": "model_diagnostics",
              "type": "image/png"
       },
      {
              "id": "relations",
              "type": "image/png"
       },
      {
              "id": "model_prediction",
              "type": "text/csv"
       },
      {
              "id": "metaJson",
              "type": "application/json"
       },
      {
              "id": "dataJson",
              "type": "application/json"
       }
    ]
}
Note that in contrast to a full request payload, as specified in the formal OGC WPS Interface Standard - Execute Request Section the payload for the WPS 2.0 TAMIS REST Interface is reduced to the definition of inputs and outputs, each as array. The remaining information (service, version, process identifier, execution mode and response format) are included in the REST URL or implied by the WPS instance (as explained in the URLs section).
Also note, that the definition of each input and output is reduced to id and type (which represents available MimeTypes).

Extraction of Timeseries Data From a SOS

As mentioned in section Architecture and Role of TAMIS REST component, the TAMIS WPS REST API allows the retrieval of timeseries data as input for a process execution. Inspecting the payload example above, the value of each input represents a valid SOAP GetObservation GET request against a SOS instance. The 52°North WPS may utilize this SOAP request to fetch timeseries data and use it as process input. This feature is deactivated by default and can be activated by setting the parameter filterTimeSeriesRequests to true in the wpsProxy.properties file.

However, a complete SOAP SOS GetObservation GET request is represented by a lengthy URL with many key-value-pairs as query parameters. For this reason, the 52°North Series REST API offers a RESTful and lightweight access to timeseries data. E.g. to query timeseries data via the 52°North Series REST API, a URL like http://fluggs.wupperverband.de/sos2/api/v1/timeseries/2/getData?timespan=PT12H/2013-08-06Z can be used (which filters timeseries by an optional timespan parameter). Compared to the lengthy SOAP URLs, this RESTful access is much shorter and returns a JSON encoded equivalent to the SOAP call.

So, in theory, it would be nice to replace lengthy SOAP URLs with shorter 52°North Series REST API URLs to define timeseries data as input for process execution. But the 52°North WPS is only capable of fetching timeseries data via SOAP URLs, which return XML encoded reponses. Hence, the TAMIS REST API offers the functionality to map a 52°North Series REST API URL to a valid and equivalent SOAP GetObservation GET request.


SOS URL Mapping - From Series REST API to Classical GetObservation Request

To perform the mapping, the TAMIS REST API inspects each execute input for 52°North Series REST API URLs that have to be mapped. To transform it into an equivalent and full SOS GetObservation request, the TAMIS REST API has to fetch several metadata (featureOfInterest, offering, procedure, observedProperty, temporalFilter) from the SOS instance. Again, the 52°North Series REST API can be utilized to fetch the needed data, as shown in the following example:

// series REST API timeseries query:
 http://fluggs.wupperverband.de/sos2/api/v1/timeseries/2/getData?timespan=PT12H/2013-08-06Z

// fetch needed metadata for SOS Get Observation request with URL:
 http://fluggs.wupperverband.de/sos2/api/v1/timeseries/2?expanded=true

-------------------------------------------------------------------------------------------------------------------------------------

// response of http://fluggs.wupperverband.de/sos2/api/v1/timeseries/2?expanded=true:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "2",
  "label": "Abfluss Einzelwert, Häcksbilstein",
  "uom": "m³/s",
  "station": {
    "properties": {
      "id": 66,                                                                 //featureOfInterest
      "label": "Häcksbilstein"
    },
    "geometry": {
      "coordinates": [
        7.304973185439583,
        51.063763131689065,
        "NaN"
      ],
      "type": "Point"
    },
    "type": "Feature"
  },
  "referenceValues": [
    {
      "referenceValueId": "279",
      "label": "Mittlerer Hochwasserabfluss",
      "lastValue": {
        "timestamp": 1470885750000,
        "value": 0
      }
    },
    {
      "referenceValueId": "278",
      "label": "Mittelwasserabfluss",
      "lastValue": {
        "timestamp": 1470885750000,
        "value": 0
      }
    },
    {
      "referenceValueId": "277",
      "label": "Mittlerer Niedrigwasserabfluss",
      "lastValue": {
        "timestamp": 1470885750000,
        "value": 0
      }
    }
  ],
  "firstValue": {
    "timestamp": 1155250800000,
    "value": 0.01
  },
  "lastValue": {
    "timestamp": 1470885750000,
    "value": 0
  },
  "parameters": {
    "service": {
      "id": "1",
      "label": "Wupperverband Zeitreihen Dienst",
      "serviceUrl": "http://fluggs.wupperverband.de/sos2-tamis"                 // SOS URL
    },
    "offering": {
      "id": "254",                                                              // offering
      "label": "Einzelwert"
    },
    "feature": {
      "id": "66",
      "label": "Häcksbilstein"
    },
    "procedure": {
      "id": "254",                                                              // procedure
      "label": "Einzelwert"
    },
    "phenomenon": {
      "id": "2",                                                                 //observedProperty
      "label": "Abfluss"
    },
    "category": {
      "id": "7",
      "label": "Gewässer"
    }
  },
  "renderingHints": {
    "chartType": "line",
    "properties": {
      "color": "#1E90FF",
      "lineType": "solid",
      "width": "1"
    }
  }
}

Basically, to extract the needed properties to build a SOS GetObservation request, the URL http://fluggs.wupperverband.de/sos2/api/v1/timeseries/2/getData?timespan=PT12H/2013-08-06Z is modifed to http://fluggs.wupperverband.de/sos2/api/v1/timeseries/2?expanded=true, which returns JSON encoded timeseries metadata description (in this case for the timeseries with id 2). The query parameter expanded=true returns an expanded version that includes additional metadata. From this document the missing information can be extracted, as concluded in the following table:


SOS GetObservation Request Parameter JSON Response Element
SOS URL parameters/service/serviceUrl
featureOfInterest station/properties/id
offering parameters/offering/id
procedure parameters/procedure/id
observedProperty parameters/phenomenon/id

The only GetObservation parameter left is temporalFilter, which has to be built from the initial timespan query parameter, as shown in the subsequent example. In essence, the encoded timespan is transformed into a String with explicit temporal start- and endpoint.

// timespan to temporalFilter example

timespan: PT12H/2013-08-06

// is transformed to

temporalFilter: 2013-08-05T12:00:00.000Z/2013-08-06T00:00:00.000Z

Now that all information is collected, it can be combined to a valid SOS Get Observations request, which replaces the 52°North Series REST API input.

Examples

Process Execution - Asynchronous

POST http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression?sync-execute=false HTTP/1.1
Host: tamis.dev.52north.org
Content-Type: application/json
Accept: application/json


{
    "inputs": [
      ... // omitted for readability; see payload example above
    ],
    "outputs": [
      ... // omitted for readability; see payload example above
    ]
}
HTTP/1.1 201 CREATED
Location: http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression/jobs/c8b6108-0c24d38573eb
In case of asynchronous execution, the response contains no body, but a Location header with a URL to the created job-instance, which may be used to retrieve the corresponding StatusInfo document.

Process Execution - Synchronous

POST http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression?sync-execute=true HTTP/1.1
Host: tamis.dev.52north.org
Content-Type: application/json
Accept: application/json


{
    "inputs": [
      ... // omitted for readability; see payload example above
    ],
    "outputs": [
      ... // omitted for readability; see payload example above
    ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "result": [
    {
      "ID": "modelDiagnostics",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0modelDiagnostics.e9e25149-2988-4da3-abe7-32897e6e7f6c"
    },
    {
      "ID": "relations",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0relations.2f57bbe8-d842-4517-99bf-5afc87b4f318"
    },
    {
      "ID": "modelPrediction",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0modelPrediction.06619995-83ed-4872-8a4e-86a928286c63"
    },
    {
      "ID": "metaJson",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0metaJson.f367b0f8-a762-4b39-b470-e352c3a54b8a"
    },
    {
      "ID": "dataJson",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0dataJson.05d92ba0-975a-4457-aa1d-cd7975933f86"
    }
  ]
}
In case of synchronous execution, the response represents the corresponding Result document.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET <base-url>/processes/{process-id}/jobs/{job-id} application/json Returns a StatusInfo document for the specified process with id {process-id} and job with id {job-id}.
Note that job instances are deleted from time to time. Hence, a certain {job-id} will become invalid after a certain period of time!

Examples

Get Status Example - Process Accepted

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression/jobs/c8b61082-6-83d0-0c24d38573eb HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "StatusInfo": {
        "JobID": "c8b61082-688b-46f8-83d0-0c24d38573eb",
        "Status": "Accepted",
        “Progress”:42
    }
}
Note that parameter Status is set to Accepted and parameter Progress indicates the percentage of job completion (if supported by the WPS instance).
Note that in contrast to a full StatusInfo response, as specified in the formal OGC WPS Interface Standard - StatusInfo Document Section, the response of the WPS 2.0 TAMIS REST Interface is reduced to JobID, Status and Progress (which corresponds to formal PercentCompleted from the standard). The remaining information (expiration date, estimated completion and next poll) is omitted.

Get Status Example - Process Finished

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression/jobs/c8b61088-83d0-0c24d38573eb HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "StatusInfo": {
        "JobID": "c8b61082-688b-46f8-83d0-0c24d38573eb",
        "Status": "Successful"
        “Outputs”: “http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression/jobs/c8bc24d38573eb/outputs”
    }
}
Note that parameter Status is now set to Successful and that there is a new parameter Outputs that contains a link to the outputs of the finished job, encoded as a Result document.

Get Status Example - Process Failed

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression/jobs/c8b610-83d0-0c24d38573eb HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "StatusInfo": {
        "JobID": "c8b61082-688b-46f8-83d0-0c24d38573eb",
        "Status": "Failed"
        “Exceptions”: “http://tamis.dev.52north.org/wps-proxy/processes/org.n52.wps.server.r.tamis-rest-prediction-single/jobs/16f3d17-58362b466cb8/exceptions”
    }
}
Note that parameter Status is now set to Failed and that there is a new parameter Exceptions that contains a link to one or more exceptions that occurred during the execution of the job, encoded as a ExceptionReport document (An example can be seen below).
ExceptionReport Example
GET http://tamis.dev.52north.org/wps-proxy/processes/org.n52.wps.server.r.tamis-rest-prediction-single/jobs/16f3d1f5-58362b466cb8/exceptions HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
							
{
  "ExceptionReport": {
    "Exceptions": [
      {
        "Code": "InvalidParameterValue",
        "Locator": input identifier,
        "Text": [
          "org.n52.wps.server.ExceptionReport: Input Identifier is not valid: xyz"
        ]
      }
    ]
  }
}
Note that in contrast to a full StatusInfo response, as specified in the formal OGC WPS Interface Standard - StatusInfo Document Section, the response of the WPS 2.0 TAMIS REST Interface is reduced to JobID and Status and a new parameter Outputs. The remaining information (expiration date, estimated completion and next poll, percentCompleted) is omitted.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET <base-url>/processes/{process-id}/jobs/{job-id}/outputs application/json Returns a Result document for the specified job with process id {process-id} and job id {job-id}. It comprises all requested outputs for the specified job.
GET <base-url>/processes/{process-id}/jobs/{job-id}/outputs/{output-id} application/json Returns a single output entry with id {output-id} for the specified job with process id {process-id} and job id {job-id} . In contrast to a complete Result document, the encoded JSON response only displays the information of that specific output (without surrounding Result and Output elements)
Note that job instances are deleted from time to time. Hence, a certain {job-id} will become invalid after a certain period of time!
The desired output format (application/json) may be transmitted in three ways:
  • in the Accept header: Accept: application/json
  • as query parameter format of the request: <baseURL>/processes/{process-id}/jobs/{job-id}/outputs?format=json or <baseURL>/processes/{process-id}/jobs/{job-id}/outputs/{output-id}?format=json respectively
  • as URL suffix .json: <baseURL>/processes/{process-id}/jobs/{job-id}/outputs.json or <baseURL>/processes/{process-id}/jobs/{job-id}/outputs/{output-id}.json respectively

Examples

Get Result Example - Complete Result Document

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression/jobs/c8b61082-6d38573eb/outputs HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "result": [
    {
      "ID": "modelDiagnostics",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0modelDiagnostics.e9e25149-2988-4da3-abe7-32897e6e7f6c"
    },
    {
      "ID": "relations",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0relations.2f57bbe8-d842-4517-99bf-5afc87b4f318"
    },
    {
      "ID": "modelPrediction",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0modelPrediction.06619995-83ed-4872-8a4e-86a928286c63"
    },
    {
      "ID": "metaJson",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0metaJson.f367b0f8-a762-4b39-b470-e352c3a54b8a"
    },
    {
      "ID": "dataJson",
      "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=d9dc5248-e741-4ef0-a54fee1a0dataJson.05d92ba0-975a-4457-aa1d-cd7975933f86"
    }
  ]
}
Note that in contrast to a full GetResult response, as specified in the formal OGC WPS Interface Standard - Result Document Section, the response of the WPS 2.0 TAMIS REST Interface is reduced to JobID and the Output array. The remaining information (expiration date) is omitted.
Also note, that the description of each Output is simplified as opposed to the formal definition from the standard.

Get Result Example - Single Output

GET http://tamis.dev.52north.org/tamis-rest/api/v1/services/1/processes/org.n52.wps.server.r.tamis-regression/jobs/c8b6138573eb/outputs/modelDiagnostics HTTP/1.1
Host: tamis.dev.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "ID": "modelDiagnostics",
  "value": "http://tamis.dev.52north.org:80/wps/RetrieveResultServlet?id=23edc065-8882-45c4-a9af-92fmodelDiagnostics.00c30ab96-8f79b4678671"
}
Note, that the description of the Output is simplified as opposed to the formal OGC WPS Interface Standard - Result Document Section.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
DELETE <base-url>/processes/{process-id}/jobs/{job-id} application/json Stops/Deletes an existing job with the id {job-id} for process with id process-id. On valid dismiss, returns HTTP status 200 - OK.
Note that subsequent calls to the same or non-existing {job-id} result in a HTTP status code 404 - NOT FOUND.
Currently (as of 2016-08-09), the operation is not yet implemented in the 52°North WPS. Hence, the REST-API call will fail and the job with id {job-id} still exists!.