Creating a Ruby API

Question

I have been tasked with creating a Ruby API that retrieves youtube URL's. However, I am not sure of the proper way to create an 'API'... I did the following code below as a Sinatra server that serves up JSON, but what exactly would be the definition of an API and would this qualify as one? If this is not an API, how can I make in an API? Thanks in advance.

require 'open-uri'
require 'json'
require 'sinatra'

# get user input
puts "Please enter a search (seperate words by commas):"
search_input = gets.chomp
puts
puts "Performing search on YOUTUBE ... go to '/videos' API endpoint to see the results and use the output"
puts

# define query parameters
api_key = 'my_key_here'
search_url = 'https://www.googleapis.com/youtube/v3/search'
params = {
  part: 'snippet',
  q: search_input,
  type: 'video',
  videoCaption: 'closedCaption',
  key: api_key
}

# use search_url and query parameters to construct a url, then open and parse the result
uri = URI.parse(search_url)
uri.query = URI.encode_www_form(params)
result = JSON.parse(open(uri).read)

# class to define attributes of each video and format into eventual json
class Video
attr_accessor :title, :description, :url
def initialize
    @title = nil
    @description = nil
    @url = nil
end
def to_hash
    {
        'title' => @title,
        'description' => @description,
        'url' => @url
    }
end
def to_json
    self.to_hash.to_json
end
end

# create an array with top 3 search results
results_array = []
result["items"].take(3).each do |video|
  @video = Video.new
  @video.title = video["snippet"]["title"]
  @video.description = video["snippet"]["description"]
  @video.url = video["snippet"]["thumbnails"]["default"]["url"]
  results_array << @video.to_json.gsub!(/\"/, '\'')
end

# define the API endpoint
get '/videos' do
  results_array.to_json
end

Answer 1

I think they want you to create a third-party library. Imagine you are schizophrenic for a while.

Joe wants to build a Sinatra application to list some YouTube videos, but he is lazy and he does not want to do the dirty work, he just wants to drop something in, give it some credentials, ask for urls and use them, finito.

Joe asks Bob to implement it for him and he gives him his requirements: "Bob, I need YouTube library. I need it to do:"

# Please note that I don't know how YouTube API works, just guessing.
client = YouTube.new(api_key: 'hola')
video_urls = client.videos # => ['https://...', 'https://...', ...]

And Bob says "OK." end spends a day in his interactive console.

So first, you should figure out how you are going to use your not-yet-existing lib, if you can – sometimes you just don't know yet.

Next, build that library based on the requirements, then drop it in your Sinatra app and you're done. Does that help?

Answer 2

An "API = Application Program Interface" is, simply, something that another program can reliably use to get a job done, without having to busy its little head about exactly how the job is done.

Perhaps the simplest thing to do now, if possible, is to go back to the person who "tasked" you with this task, and to ask him/her, "well, what do you have in mind?" The best API that you can design, in this case, will be the one that is most convenient for the people (who are writing the programs which ...) will actually have to use it. "Don't guess. Ask!"

A very common strategy for an API, in a language like Ruby, is to define a class which represents "this application's connection to this service." Anyone who wants to use the API does so by calling some function which will return a new instance of this class. Thereafter, the program uses this object to issue and handle requests.

The requests, also, are objects. To issue a request, you first ask the API-connection object to give you a new request-object. You then fill-out the request with whatever particulars, then tell the request object to "go!" At some point in the future, and by some appropriate means (such as a callback ...) the request-object informs you that it succeeded or that it failed.

"A whole lot of voodoo-magic might have taken place," between the request object and the connection object which spawned it, but the client does not have to care. And that, most of all, is the objective of any API. "It Just Works.™"