Building a Telegram bot: the words API
Tags: go, tutorial, programming, bots
Published: 2021-02-08 14:00:52

In the first post of this series we created our Telegram bot and managed to make it reply to any message with a fixed response.

Today we'll go a step forward and connect it to the API to start searching for words.

####The words API 🎧
We'll be using the [WordsAPI](https://www.wordsapi.com). The endpoint we'll need is 
```
GET https://wordsapiv1.p.mashape.com/words/{word}
``` 
This will perform a search with the word we provide as a parameter on the URL and return the results with a lot of info about the word, in our case, we'll only use the definition, synonyms, antonyms, and examples of use.
You can check out this Postman collection to give it a try: [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.postman.co/run-collection/e1684d65483ccc9a4583)

####Creating the API client 🔄
We'll create a Go package that will help us make requests to the API. The package will live in the `pkg/words` folder.
To be initialized, it will need the `baseURL`, the `token`, and an http `client`:
```golang
type API struct {
	token   string
	baseURL string
	client  *http.Client
}

func New(baseURL, token string, client *http.Client) *API {
	return &API{
		token:   token,
		baseURL: baseURL,
		client:  client,
	}
}
```
Then we'll need a struct in which to store the JSON resulting from the request to the API. For our use case, we don't need all the properties that the request will return, we can specify on the Go `struct` the ones we need:
```golang
type responsePayload struct {
	Word    string   `json:"word"`
	Results []Result `json:"results"`
}

type Result struct {
	Definition string   `json:"definition"`
	Synonyms   []string `json:"synonyms,omitempty"`
	Antonyms   []string `json:"antonyms,omitempty"`
	Examples   []string `json:"examples"`
}
```
Last but not least, we need to create the function that will make the actual request. We will pass the word as a parameter and add the `x-rapidapi-key` with our token:
```golang
func (api *API) Word(word string) ([]Result, error) {
	url := fmt.Sprintf("%s/%s", api.baseURL, word)

	// create the request to the words endpoint
	req, err := http.NewRequest(http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}

	// add the token to the headers
	req.Header.Add("x-rapidapi-key", api.token)

	// make the request
	res, err := api.client.Do(req)
	if err != nil {
		return nil, err
	}

	// read the response
	body, err := ioutil.ReadAll(res.Body)
	defer res.Body.Close()
	if err != nil {
		return nil, err
	}

	// parse the json
	var payload responsePayload
	err = json.Unmarshal(body, &payload)
	if err != nil {
		return nil, err
	}

	return payload.Results, nil
}
```
With that, we have everything we need to interact with the WordsAPI, we can give it a try like this:
```golang
api := New("https://wordsapiv1.p.rapidapi.com/words", "{the_token}", http.DefaultClient)
result, _ := api.Word("big")
```

Check the code here: https://github.com/albarin/dictiobot/tree/02-the-words-api

In the next and last post of this series, we'll tie everything together and show the results of the word search in Telegram.

See you soon! 👋