# Custom Web Services

The *WireBootstrap Custom Data Connector* is included in the core WireBootstrap framework.  The *WireBootstrap Custom Data Connector* allows custom web services to be used with data sources.  These are services developed by in-house teams or third party vendors hosted on-premise or in the cloud.

## Provider Key

Use the `custom` provider key to use the service provider for this data connector with a data source.

```javascript
const service = new wire.data.DataSource("custom", {
    ...    
});
```

## Web Service Calls

URLs for making service calls are created using the standard template below.

```javascript
[root]/[method]?[filters]
```

| URL Element | Description                                                                                                                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| root        | The root to be used in web service calls.  This will be the [ServiceRoot](https://docs.wirebootstrap.com/wirebootstrap/reference/wire.data/wire.data.datasource#properties) set on the data source. |
| method      | The method to call on the web service.  This will be the entity set in a table query in the `from` clause.                                                                                          |
| filters     | Any filters passed to the method.  These are set up in the table query `where` clause.                                                                                                              |

Consider the following query.

```javascript
const service = new wire.data.DataSource("custom", {
    ServiceRoot: "https://service-reporting"
});

const query = wire.data.select().from("sales")
    .where()
        .eq("product", "PRD-001")
        .eq("territory", "East");
        
const result = service.exec(query);
```

When using this query with the custom web service provider, the following URL is constructed and used to call the web service.

```javascript
https://service-reporting/sales?product=PRD-001&territory=East
```

### GET vs POST

The previous query will result in a `GET` HTTP method being used for the web service call.  To use a `POST` with custom data, change the where clause in the filter to use the `custom` method to send up any custom data to the method in the body of the request.

In the example below, the same query will be posted to the service.

```javascript
...

const filter = { product: "PRD-001", territory: "East" }

const query = wire.data.select().from("sales")
    .where()
        .custom(filter)

...
```

For more on creating and executing queries, visit [Connecting to Data](https://docs.wirebootstrap.com/wirebootstrap/connecting-to-data/data-connectors) and [Creating Queries](https://docs.wirebootstrap.com/wirebootstrap/creating-queries/select-queries).

## Configuration

| Name       | Default | Description                                                                                                                                                                          |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| params     |         | Custom parameters to send with query requests.  See [details](https://docs.wirebootstrap.com/wirebootstrap/connecting-to-data/data-connectors/broken-reference) below.               |
| testMethod |         | This method used to test the connection to the data service.  See [details](https://docs.wirebootstrap.com/wirebootstrap/connecting-to-data/data-connectors/broken-reference) below. |

### Params

Sometimes its helpful to be able to send custom parameters in the web service calls that are outside of any query filters.  Use the provider `params` configuration option to set these up.

```javascript
const service = new wire.data.DataSource("custom", {
    ServiceRoot: "https://service-reporting",
    Provider: {
        params: {
            option1: "value1",
            option2: "value2"
        }
    }
});
```

In the example above,  two extra parameters called `option1` and `option2` will be set up in the URL and sent to the data service.

```javascript
https://service-reporting/sales?product=PRD-001&territory=East&option1=value1&option2=value2
```

## Allow

Service providers are able to tell consumers about the functionality they support through an [`allow`](https://docs.wirebootstrap.com/wirebootstrap/connecting-to-data/data-connectors#allow) property.  Below is a list of the functionality that the custom service provider supports.

| Name               | Supports |
| ------------------ | -------- |
| delete             | true     |
| discover           | false    |
| storedProcedure    | false    |
| tableQuery         | true     |
| tableQuery.orderBy | false    |
| tableQuery.groupBy | false    |
| test               | true     |
| write              | true     |

### Test Method 

The custom service provider supports testing if the service is available. However, the method to be used for this needs to be specified in the `testMethod` configuration option.

```javascript
const service = new wire.data.DataSource("custom", {
    ServiceRoot: "https://service-reporting",
    Provider: {
        testMethod: "test"
    }
});

const available = service.test();
```