Setting up the data connector config file

This README is intended for contributors and developers who want to build a configuration file. This readme will outline the process to build a configuration file for Yelp's phone number search API.

You can review the Yelp API documentation to determine the available endpoints here.

Inspecting endpoints

“Endpoints are communication channels. When an API interacts with another system, they communicate with each other and allows you to match business data on the information you provide.”

Once you choose an endpoint, review its documentation. Make a note of the HTTP request method (e.g., GET, PUT, etc) and the specific source.

In the parameter section, select the targets you want as a response for your app.

“A parameter is an option that can be passed with the endpoint to influence the response”.

Obtaining an access token

Yelp requires each user to have an access token to make API requests on their behalf. An access token represents the authorization of a specific application to access particular parts of a user's data. Start here to generate the access token. (You will create an app, provide the required information about its use to generate the token.)

Now that you created your token, it’s time to create the config files.

The config files

The data connector requires two files to run, meta.json and table.json.

Create the meta.json file

The meta.json file contains the key value of the table and its name in an array. It tells the connector how many tables are in the data source and which tables to access. The meta.json file needs to manually written.

Create the businesses.json file

The business file contains information needed to communicate with Yelp’s API. In this file, there is the request and response section.

Top Level

Request:

URL: "https://api.yelp.com/v3/businesses/search/phone"

• Contains the URL path for the API

method: "GET"

• GET is used to request data from a specified resource, For the Yelp's API request, leave it as GET.

authorization: "Bearer"

• Authorization to ensure that client requests access data securely. The Bearer allows requests to authenticate using an access key, such as a token. For Yelp's API request, leave it as Bearer.

• Note: For other API’s, please read how they may authorize your application. Depending on the method, a different authorization may be required.

Params: {"phone": true}

• Parameters, or Params, contain the requested criteria to the API. Before creating the config file, the parameters should be selected. Each parameter as a key-value pair where the name is the key and the value is Boolean. If you take a look at the Yelp Phone Search documentation, it shows that phone is a required parameter.
  • A True value refers to the required parameter to query a request.
  • A False value refers to the optional parameter to query a request.

Response:

ctype: "application/json"

• The Content-Type, or ctype, is used to indicate the media type of the resource. A Content-Type header tells the client what the content type of the returned information actually is. With data connector, the contect type is application/json.

tablePath: "$.businesses[*]"

• When the response is received it delievers an array and under the array is the table content. With data connector and Yelp, the tablePath is $.businesses[*].

schema: { }

• After finding table content, it looks at schema.

id: {"target": "$.id", "type": "string"}

• The schema will be read until all elements of the business array received. ID is at the root of the first row of the business array, and it will access the ID attribute.

• To build the schema, you would need to review the response section of the specific endpoint page.

The user selects the responses they are interested in and sets them up in the appropriate format. Take a look at the response section of the page. The target is the response name, and the type is the data format response generated.

Once the user sets up the appropriate responses in the Json file then the user can start up the data connection.

That's all for now

Please visit the other tutorials that are available if you are interested in setting up a data connector.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Weiyuan Wu 💻 🚧

peiwangdb 💻 🚧

nick-zrymiak 💻

Pallavi Bharadwaj 💻

Hilal Asmat 📖

This project follows the all-contributors specification. Contributions of any kind welcome!