Skip to content
Simple API to get YouTube (direct) video URLs - used in my Movie Critic Alexa skill and Bixby capsule.
JavaScript Shell
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Movie Critic API 👾

API for use in my Movie Critic Alexa Skill and Bixby Capsule.

Simple and light-weight (doesn't use any framework such as express).

Getting started 💻

  1. Clone the repository

  2. Install Node using Node Version Manager (NVM)

     $ curl -o- | bash
     $ nvm install 10.16

    A .nvmrc file is also included in the project for reference.

  3. Install project dependencies

     $ npm i


  • GET <base URL>/you-tube/{id} - Get streaming url of a single YouTube video.
  • GET <base URL>/you-tube?ids=id1,id2 - Get streaming urls of multiple (comma seperated IDs) YouTube videos.

Base URLs

  • dev: Check the AWS console, or Serverless deployment output.
  • prod:*

*Using a custom domain is optional - I'm using the serverless-domain-manager plugin. To use without a custom domain, remove the customDomain section from custom in serverless.yml, and remove reference to the serverless-domain-manager plugin

Note: To help reduce latency on the prod API, GET responses are cached for 900 seconds - For more details see here.


The x-api-key header is required. The key is generated at deploy time - check the AWS console, or Serverless deployment output.

Respose body


  • GET <base URL>/you-tube/{id}

    { "url": "https://..." }
  • GET <base URL>/you-tube?ids=id1,id2

      "id1": "https://...",
      "id2": "https://..."


{ "message": "Invalid HTTP Method: POST" }


{ "error": "Houston, we have a problem!" }


See responses for details.

Running and debugging 🐛

You can run and debug this locally using serverless-offline.

  1. Run npm run start.

    A bundle is built using ncc, and a local server is started.

  2. Using the local endpoint output to the console, send a request using Postman.

    You don't need the x-api-key header when running locally.

Deploying 🤖

Depending on the stage you're deplpoying to simply run either:

  • dev - npm run deploy:dev
  • prod - npm run deploy:prod

Deployment currently assumes that AWS credentials are available, under the personal profile.

Branches 🌳

The repo has 2x main branches:

  • master - This is generally what is deployed to to stage prod.
  • develop - This is generally what is deployed to to stage dev.

Branches and PRs are created for new changes, and merged to develop -> master.

Keeping the Lambda warm 🔥

For prod stage, I'm using the serverless-plugin-warmup to prevent cold starts, and therefore ensure latency is kept to a mimnimum.

CI/CD ♻️

Automatic deployments

Automatic deployments are done with GitHub Actions, triggered by either a commit to develop or master branches.

  • develop: Deploys using stage dev.
  • master: Deploys using stage prod.

Following deployment, a bash script is executed. This gets the API Gateway endpint from Serverless, and sends a HTTP request - if the http status code from the response is not 200, it exits with code 1 and the build essentially fails.


  • Add tests.
  • Add JSDoc where needed.
  • Add ESLint.

Usage and license

  • Provided with an MIT license.
  • Forks welcome (would appreciate credit and/or a link back where necessary).
You can’t perform that action at this time.