Youtube Search API - Aivo Technical Challenge

General requirement

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

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’)

(*) - 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.

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

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

Project guidelines

• Must be developed in PHP7:
  • 13/03/2021: Developed using PHP's newest version as of today: PHP 7.4.16
  • 26/02/2023: Upgraded to PHP 8.2.3
  • 18/06/2025: Upgraded to PHP 8.4.8
• Framework of your choice (Optional):
  • 13/03/2021: Developed with Laravel 8
  • 26/02/2023: Upgraded to Laravel 10
  • 18/06/2025: Upgraded to Laravel 12
• The project must be available on GitHub or BitBucket:
  • GitHub was chosen, in the present repository: MatiasCarabella/youtube-search-API (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. Clone the project and cd into it:

git clone https://github.com/MatiasCarabella/youtube-search-API.git
cd youtube-search-API

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

• Windows: copy .env.example .env
• Linux: cp .env.example .env

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

PHP 🐘 | Composer 🎻

Pre-requisites:

• PHP8 installed
• Composer installed

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 🐋

Pre-requisites:

• Docker installed
• Docker Compose 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:

{
  "message": "The given data was invalid.",
  "errors": {
    "search": [
      "The search field is required."
    ]
  }
}

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 'search' query param with the text to search 🔍

The only other mandatory element is the auth via 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:

Formatting

This project uses PHP CS Fixer to ensure consistent code style. The formatting rules are defined in the .php-cs-fixer.php file at the project root.

To automatically format your code, run:

composer format

If you are using an unsupported version of PHP, you may need to bypass the version check:

Powershell: $env:PHP_CS_FIXER_IGNORE_ENV=1; composer format | Bash: PHP_CS_FIXER_IGNORE_ENV=1 composer format

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

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