# Web Service

## Web Service

### Introduction

Hop has a simple way of exposing data through a servlet.

For more information on configuring the Hop server check the [Hop Server docs](https://github.com/mbertazz/hop-docs-md/blob/main/modules/ROOT/pages/hop-server/hop-server/index.1Z5rVwc6I4)

### Web Service Metadata

#### Screenshot

![Web Service metadata example](/files/4W6ell2ic0kqS7p1lN7Y)

#### Options

| Option                        | Description                                                                                                                                                      |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                          | The name of the web service. This is the name that is passed into the webService URL.                                                                            |
| Enabled                       | Enables or disabled the web service                                                                                                                              |
| Filename on the server        | This is the filename on the server. Make sure that the pipeline you want to execute is available on the server.                                                  |
| Output transform              | The name of the transform from which this service will take the output row(s).                                                                                   |
| Output field                  | The output field from which this service will take data from, convert it to a String and output it                                                               |
| Content type                  | The content type which will get reported by the webService servlet                                                                                               |
| List status on server         | Enable this option if you want the executions of the web service pipeline to be listed in the status of the server.                                              |
| Request body content variable | This is the name of the variable which at runtime will contain the content of the request body content. This is useful when doing a POST against the webservice. |

### Hop Server configuration

Your Hop Server needs to know about the metadata you defined. As stated above you need to make sure the server has access to the pipeline(s) you want to execute as well as the server metadata.

The best way to do this is to set the following option in your XML configuration file:

Linux

```highlight
<metadata_folder>/path/to/your/metadata</metadata_folder>
```

Windows

```highlight
<metadata_folder>C:\\path\\to\\your\\metadata</metadata_folder>
```

A simple example would be:

```highlight
<hop-server-config>
  <hop-server>
    <name>8181</name>
    <hostname>localhost</hostname>
    <port>8181</port>
  </hop-server>
  <metadata_folder>/home/hop/project/services/metadata</metadata_folder>

</hop-server-config>
```

### Using the service

#### Base request (ATTENTION: Use the S word capitalized)

```highlight
http://<hop-server-url>/hop/webService
```

#### Request parameters

| Parameter          | Description                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `service`          | The name of the service. This corresponds to the Web Service metadata object.                                                   |
| `runConfig`        | The name of the pipeline run configuration. Please note that returning values is only supported on the "Local" pipeline engine. |
| Any parameter name | Any parameter can be set simply by passing the value through the request URL                                                    |
| Any variable name  | Any variable can be set simply by passing the value through the request URL                                                     |

#### POST

Beside the default GET you can also do a POST against the web service and pass in a request body. The content of this body is then picked up if you set the request body content variable. This variable will contain the body content every time the POST request triggers the execution of the underlying pipeline.

#### Request example

The following executes Hop Web Service `test` as seen in the screenshot above. It passes a parameter B and a variable A and outputs JSON produced by a JSON Output transform.

```highlight
http://localhost:8181/hop/webService/?service=test&A=valueA&B=valueB
```

The web service pipeline looks like this:

![Web Service pipeline example](/files/LdpeSL7RAhjs3vFR6WT4)

Last updated 2025-09-04 18:20:53 +0200


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.primeur.com/data-shaper-1.21/data-shaper-engine/index/web-service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.