Youtube Search API - Aivo Challenge - Technical Document

General requirement

Develop an endpoint that returns up to 10 results from a YouTube search, given a keyword

Mandatory parameters

• published_at (*)
• id
• title
• description
• thumbnail

(*) - It is noted that the 'snakecase' notation is used, so all other parameters will adhere to this convention.

Optional parameters

• extra (additional data that you want to add at your discretion)

In regards to this, I decided to add the parameters direct_link and channel_title, so each video will have the following format:

{
   "published_at":"2011-10-19T02:42:54Z",
   "id":"1G4isv_Fylg",
   "title":"Coldplay - Paradise (Official Video)",
   "description":"Coldplay - Paradise is taken from the album Mylo Xyloto released in 2011 [...]",
   "thumbnail":"https://i.ytimg.com/vi/1G4isv_Fylg/default.jpg",
   "extra":{
      "direct_link":"https://www.youtube.com/watch?v=1G4isv_Fylg",
      "channel_title":"Coldplay"
   }
}

The list of fetched videos will be contained in a videos parameter, which will share the 'top level' of the response JSON with the following general parameters:

• total_results
• results_per_page
• next_page_token (*) (makes it possible to navigate between the result pages)
• prev_page_token (*) (same as ‘next_page_token’)

Finally, the general format of the response will be as follows:

{
   "next_page_token":"CAEQAA",
   "total_results":1000000,
   "results_per_page":1,
   "videos":[
      
   ]
}

(*) - The next_page_token parameter will only appear if there are more pages of results, likewise, prev_page_token will only appear if we are not positioned on page 1.

Project guidelines

• Must be developed in PHP7:
  • (13/03/2021): Developed using PHP7's newest version as of today: PHP 7.4.16
  • (Update 26/02/2023): Upgraded to the most recent version: PHP 8.2.3
• Framework of your choice (Optional):
  • (13/03/2021): Developed with Laravel 8
  • (Update 26/02/2023): Upgraded to Laravel 10
• The project must be available on GitHub or BitBucket:
  • GitHub was chosen, in the present repository: MatiasCarabella/youtubeSearchAPI (github.com)
• The project must be testable locally, with the necessary documentation on how to do it:
  • Correct, I will be addressing the simple process of how to get the application running in the next section.
• Tests (Optional):
  • The project was made more robust with the addition of tests, which I will also detail later.
• Any added value is welcome:
  • The application accepts a series of optional arguments. These are:
    • api_key (holds the mandatory authentication key to use the Google/Youtube API, if this parameter is absent it uses the API_KEY_DEFAULT from the .env file)
    • results_per_page (modifies the number of results per page, up to 10 as indicated in the project requirement, if this parameter is absent the default is also 10)
    • page_token (allows to navigate between the different pages of results, making use of the parameters next_page_token and prev_page_token, if this parameter is absent it simply defaults to page #1)

Installation

1. Generate the folder where you'll download the project, access it from the terminal/console of preference and run the following commands:

git init
git pull https://github.com/MatiasCarabella/youtubeSearchAPI.git

2. Copy the .env file (Optional: Set a custom API_KEY_DEFAULT value)

copy .env.example .env (Windows)

cp .env.example .env (Linux)

Now, in order to get the application up and running, you have two options:

PHP | Composer | Artisan

Requirements:

• PHP8 installed.
• Composer installed (dependency manager).

1. Run the following command to download the necessary dependencies:

composer install

2. Generate the encryption key

php artisan key:generate

3. Now you can run the project from its root folder whenever you want, using the following command:

php artisan serve

All done!

Docker compose 🐋

Requirements:

• Docker installed.

1. Run the following command in the project root folder to build & start the application:

docker compose up

All done!

Using the API

Onto the fun bit, now we're able to use the API. The URL of the endpoint is the following:

http://localhost:8000/api/youtube-search

If we access this URL from a web browser, we'll see something like this:

That's to be expected (since we haven't specified the text to search for), but it gives us confirmation that the API is running successfully!

Now, to effectively test the service we can use a client like Postman:

As you can see, it's simply a matter of sending a JSON body with the text to search for in the 'search' field:

{
    "search": "Paradise"
}

The only other mandatory element is the api_key, which can be generated on the Google Cloud Platform.

This can be configured in two ways:

• As a Request header ('api_key': 'XXXXXXXXXXXXX')

• As the value of the API_KEY_DEFAULT variable from the projects' env file (When not sent as a header, it is read from here)

API_KEY_DEFAULT=XXXXXXXXXXXXX

In both cases, if an invalid api_key is set (or if there's no api_key), an error will be displayed as returned by the Google API:

Finally, as we mentioned earlier, the optional fields results_per_page and page_token are also available.

Notes

• If an invalid value is entered in the results_per_page parameter, it defaults to 10.
• If an invalid value is entered in the page_token or api_key parameters, an error message will be displayed as returned by the Google API.

Project structure

The bulk of the application's logic is on the following files:

routes->api.php

app->Http->Controllers->YoutubeController.php

app->Services->YoutubeServices.php

tests->Feature->YoutubeTest.php

In order to facilitate the understanding of the code, everything is commented accordingly:

Tests

There are some tests that can be run to make sure the application functions properly. These are:

1. Validate that an example query returns HTTP status 200 - OK.
2. Validate that the JSON response format matches to the stipulated one.

To execute them, simply run the following command from the project root folder:

php artisan test tests/Feature/YoutubeTest.php

Closing thoughts

I am happy to say that the ‘Have fun!’ bit from the Challenge's description was also achieved, I really enjoyed the project!

Special thanks to @DaianaArena for creating the banner image.

To whoever read this far, thank you very much and best regards!

Matías Carabella - Back-end Developer