# Building a Data Connector

WireBootstrap client-side Data Connectors use  *service providers* to connect to web services.  

A WireBootstrap service provider is a JavaScript function or class that implements the methods and properties expected by the data source based on the functionality of the service provider.

This section documents a sample service provider created to query the public JSON Placeholder web service at [https://jsonplaceholder.typicode.com](https://jsonplaceholder.typicode.com/).  The sample is available in a sub-project inside any edition of the [WireBootstrap for Gentelella](https://www.wirebootstrap.com/products/gentelella.html) download.  Once downloaded, go to the`\docs\building-a-data-connector` directory to open the project containing the examples in this section.  Double-click the index.html file to run the sample.

## Create the Provider

The service provider is a simple JavaScript class or function that takes one configuration parameter.  If needed, use the `dataSource` property on the configuration parameter to get a reference to the configuration passed into the calling data source.

```javascript
const JsonPlaceHolderServiceProvider = function (config) {

  const datasource = config.dataSource;
  ...
  
}
```

### Provider Configuration

Any service provider specific information for the data connector can be passed in using the `Provider` attribute when configuring the data source.

The example below passes in an API key that will be used by the service provider to authenticate calls to the web service.  This key is not needed for the JSON Placeholder web service.  Its used here only for demonstration.

```javascript
  const source = new wire.data.DataSource("jsonplaceholder", {
    ...
    Provider: {
      apiKey: "my-test-key"
    }
  });
```

This configuration can then be read in and used by the service provider.

```javascript
const JsonPlaceHolderServiceProvider = function (config) {

  const datasource = config.dataSource;
  const provider = datasource.Provider;
  const apiKey = provider.apiKey;  
  ...
  
}
```

For more information on data source configuration, visit [DataSource](https://docs.wirebootstrap.com/wirebootstrap/reference/wire.data/wire.data.datasource).

## Register the Provider

Register the service provider with the WireBootstrap framework by calling the `wire.data.provider.register` method.

```javascript
wire.data.provider.register({
    id: "jsonplaceholder",
    provider: JsonPlaceHolderServiceProvider
});
```

## Allow

The service provider in this example is able to transform WireBootstrap table queries into requests to the data service for data.  The service provider tells the data source about this feature by setting the `allow.tableQuery` property to `true`.

```javascript
...

this.allow = {
    tableQuery: true
}
```

## Execute Queries

The `execAsync` method on the service provider will be called by a data source to execute queries against the data service.  This method takes a [TableQuery](https://docs.wirebootstrap.com/wirebootstrap/reference/wire.data/wire.data.tablequery) parameter with the inputs to the query.

In the example below, the `getUrl` method in the project will return the transformed query as a string URL that can be used to call the web service.  

The `wire.get` method will make an asynchronous call to the web service to retrieve the data for the query.

```javascript
this.execAsync = function (query) {

    const url = getUrl(query);

    return wire.get(url);            

}
```

## DataTable Transform

After calling the asynchronous `execAsync` method on a service provider, the data source passes the data returned from the call to the `getResponseTable` method on the service provider.  This method is responsible for handling any data service specific formatting and returning the data in a standard [DataTable](https://docs.wirebootstrap.com/wirebootstrap/reference/wire.data/wire.data.datatable). 

The data returned from calls to the JSON Placeholder web service is a simple array of objects so the data table is easily created by passing the data into the data table's constructor.

```javascript
this.getResponseTable = function (data) {

    return new wire.data.DataTable(data);

}
```

Visit the [ExecAsync](https://docs.wirebootstrap.com/wirebootstrap/creating-queries/query-results#execasync) documentation for more details on this method.

## Putting It All Together

Consumers can now make calls to the data service using the service provider with a data source.  

The first parameter to the `DataSource` constructor below is the id `jsonplaceholder` used when the service provider was registered with WireBootstrap above.  The entity on the query is `todos` which is filtered to`userId` equal to`1`.

```javascript
const source = new wire.data.DataSource("jsonplaceholder");

const query = wire.data.select().from("todos").where().eq("userId", 1);

const result = await source.execAsync(query);
```

The code above will result in the following call to the web service.

```javascript
GET: https://jsonplaceholder.typicode.com/todos?userId=1
```