APIs are ubiquitous, but they can also be fun! In this talk, we'll take a look at using the Spotify API and Developer Portal to put together a simple app - finding Frank Sinatra's top 5 song. We'll learn about using APIs, how to connect when Authentication is necessary, and what to do with an API payload.
2. About Me
• Writing code since 1990
• Developer Advocate at Spotify
• Hail from Bu
ff
alo, NY
• Musician, currently the guitar
and vocals for Kings
Highwaymen
3. Talk Goals
• The history of Rails and why
Ruby developers focus on it
• A brief history of Sinatra
• A look at making a simple app
using Sinatra and the Spotify
API
• Potential Sinatra Gotchas
This talk is focused on three things: Why do we use alternate frameworks and how can they be a bene
fi
t to us, What is it like to get started with an API, and how can we get something simple to start something much larger. The
“gotcha” section is really just a little part of it. We will try to step into building a simple application that can be expanded and stretched to get something we are truly looking to do. To do this, we’ll be using Ruby, the web framework
Sinatra, and the Spotify API (available at developer.spotify.com)
4. FULL DISCLOSURE
❖ I don’t hate Rails - let’s just be clear. This talk isn’t meant to
disparage Rails or folks who love Rails - there will be no Rails
bashing (probably).
Before we get started, let’s address the elephant in the room. You might be thinking “You said Ruby PJ, why aren’t we using Rails?” Rails is great. It really is what you
need for large scale production applications most of the time. It has history. And if you got started in Ruby working on the web, chances are Rails is what you are most
familiar with.
5. Why is Ruby on Rails so
great?
Many developers came to Rails by default. Maybe we were Ruby hobbyists looking to move to the web, maybe we were web developers looking for the next great
language. Maybe we learned to code in a bootcamp, where Ruby on Rails is preferred teaching method because of its ease of use and ability to be installed nearly
universally (yes, even on windows!). Rails, when it arrived on the scene, shook up the open source world of web development. There was
fi
nally an alternative to Java,
PHP, and Perl - and it was actually fun to use. There was magic in the air!
6. The Magic
Part of the allure of Rails was the magic. I remember it being said you could build a web application in Ruby on Rails, get 90% of the work done in 10% of the time. While
the last 10% was a real pain in the crack, this was very attractive - especially to Dev shops looking to do fast turn over or convert from legacy systems to a more modern
language. Rails did things “automagically” - you had ways to handle database connections, you didn’t need to worry about straight SQL queries..I mean, heck, Rails
came with a built in index page just to let you know you we’re “Riding the Rails!” But, doing things automagically can come with problems…
7. The Rails Monolith
Rails is huge. Huge comes with a cost. One of those costs is not being able to easily
fi
nd things under the hood. I know there was a reference to this in David Heinmeir
Hansen’s keynote a few years ago. He was of course de
fi
ant and defensive. He wanted to talk about new features, but focused on why monoliths can be better than
microservices or other methods of division of application labor. And of course that’s not a surprise - David is part of the problem. Granted, he created the solution initially
- but having a Benevolent Dictator for Life can be a hinderance and part of a monolithic structure.
8. But what else is available?
This is where we get into the nitty gritty - looking at alternatives. Once upon a time, there were only a few alternatives to Rails if you wanted to put Ruby on the web.
Today, that landscape has changed. While Ruby never achieved the full framework wars of other languages (and that’s really a blessing not a burden), we have seen
growth in frameworks that can do speci
fi
c jobs better and in a more streamlined way in comparison to Rails. Let’s take a look at on of the most popular.
9. Welcome to the stage…
http://sinatrarb.com
Well, let’s take a look at Sinatra. How many folks here have used Sinatra or at least checked it out? Created by a gent named Blake Mizerany back in 2007, Sinatra was
really one of the
fi
rst steps towards using ruby on the web without Rails. Since it’s inception, Konstantin Hasse has been the main maintainer and deserves much credit
when it comes to making Sinatra a more recognizable name as time went on. Based on using routes for code to be activated, Sinatra is a lightweight solution for
applications that don’t need the overhead Rails provides.
10. The Scrappy Upstart
Even with the use of some of the API tools in Rails, Sinatra still has the upper hand when it comes to building an application that is ingesting something from an external
API. Because of it’s inherent simplicity Sinatra focuses on the task at hand with none of the over-arching strain the various parts of Rails can put on an application. Say
there is no need to retain DB records, just read and organize API pulled information - why would you build a Rails application with all the extra classes just hanging out
doing nothing? Sinatra would be the best thing for what you need to do.
11. What is an API?
Before we get started, for those not familiar with the concept, let’s talk about what an API is. API stands for Application Programming Interface. It’s literally de
fi
ned as a
set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.
APIs are ubiquitous, they are how the web is built in the modern application development setting. While our example will use a single language, framework, and API,
modern applications often have several source languages and pull from many APIs.
12. Getting Started
We’ll begin by ensuring we have an up to date version of Ruby on our system. This is done by entering the command line. On most systems, this can be done by typing
“ruby -v” into your command line as seen in the
fi
rst screen shot. For this example I’m using ruby 3.0.0, not the most recent, but it will work for our purposes.
Then we need to make a folder and give it a name. We do this with the mkdir command, as seen in the second screen shot, and we can then use cd to navigate into the
appropriate folder.
Next we will open our code editor - and here you’ll need to make a choice. Many people use VSCode, vim, emacs, or SublimeText. For the purposes of this example I’ll
be using VSCode.
Once you are in the editor of your choice, you may notice it’s empty. Since we haven’t done anything yet, this shouldn’t be a surprise. We can create a
fi
le using the
fi
le
creation tools in our editor - we’ll call it top_
fi
ve.rb
Now we are ready to get started.
13. Testing - check check
Like most things in the Ruby world, Sinatra is an extension of the language known as a gem. If you’ve used other languages, this should be familiar to you. To ensure
Sinatra is on your system AND attached to the project, run the command ‘gem install Sinatra’. There are other ways to ensure you have all the gems necessary for your
project, en masse, and we’ll discuss those later, but for now we just want to make sure what we have is working.
We’ll also want a small local server to run since this is a web based application, so we will also enter ‘gem install puma’. Puma is a simple, fast, threaded, and highly
parallel server for Ruby applications. Now, let’s write some code
14. Testing - check check
Let’s start by writing a simple hello world and making sure our server can run. In the top_
fi
ve.rb
fi
le, start by requiring the sinatra gem, then entire some simple hello world
style code as seen above. The get slash do statement tells the ruby interpreter to run the following commands as the index route to this web application. We then print
the hello world string and close the statement.
Back in the console, we give the command : ruby top_
fi
ve.rb and navigate in a browser to localhost:4567. We should be able to see…
15. Not so fancy, Slim…
A fairly basic website. Now, if you’ve been coding with Rails and you were hoping to see something more like that bottom image, I’m sorry, that isn’t going to happen.
this is part of demystifying Ruby frameworks. Rails has a lot of bells and whistles, but we want to see the power of what you can do with no ringing or shrillness.
Sinatra is basic. It’s why we want to explore other frameworks. Also, Sinatra is not automatically refreshing. So to build what we want in our example, let’s use ctrl-c in
the command line to kill the server and get into building this app.
16. Going to Spotify
You may have forgotten our main goal with building this app - to get Frank Sinatra’s top
fi
ve songs according to Spotify! Well, to handle the spotify side of things, we’ll
need an account, which is free to sign up for at developer.spotify.com. Once we have an account we can head over to our dashboard where we are allowed to create
apps.
While we aren’t building the application itself in Spotify, we will need some helpful credentials that we will get here. Let’s click, “Create an App”
17. Going to Spotify
Here we’ll create an application called Top 5 that will give us what we are looking for. We’ll
fi
ll in the App name and we can
fi
ll in the App description if we like. If this were
more than an example, it would be valuable to any developers who might come later to know what our intentions were with the application so they have a clear
understanding of our goals.
Finally, click that you understand the Terms of Service and Branding Guidelines and click create. You may also want to read those terms and guidelines.
18. Ready on one
Once we click create we should be moved to the home screen and we’ll need to click on “Settings” to get to this screen. This let’s us know our app has been created and
we are given some needed resources. Speci
fi
cally, our client ID and our client secret. No need to use them now, but as we move forward we will need to add them to our
code.
19. A little help from our friends
Part of the beauty of using Ruby for projects is the wonderful world of gems and how they can help you create a better environment to build in. While we just installed
sinatra and puma, as the need for assistance grows, we need to do things in bulk.
In walks a little gem called bundler. Bundler is a package manager for gems in Ruby. We install it just as we did sinatra, with the gem install bundler command. Then we
can use it a little di
ff
erently.
20. Creating a Gem
fi
le
To start using bundler we’ll need to create a new
fi
le in our project. This new
fi
le will list the gems we think we need and has no extension - it is simply called the Gem
fi
le
For this project our Gem
fi
le will be fairly small. We will ensure we point out that our source is the ruby gems server in the
fi
rst line and establish that we are using Ruby
3.0.0 for any coders who might come in later and need to know more about how to set up the environment to run the application.
Then we will add some gems. It may seem redundant to add sinatra and puma, but again, this is for anyone who comes after us. Additionally, we’ll add some gems we
know we’ll need like rubygems-update, bundler itself, json, and rSpotify, which will be doing a lot of the work for us in this example. We save this
fi
le in the main directory
and head to the command line to run the bundle install command.
21. Surprise, Surprise
When the bundle installs, you might notice two things. One, the number of things installed is de
fi
nitely higher than the number of things you had listed in your Gem
fi
le.
There’ no need to panic - this is why we have bundler in the
fi
rst place.
All those extra
fi
les are dependencies. Dependencies are smaller
fi
les that give the main gem an assist or help it out in some way to make it functional. Without these, our
application wouldn’t work, and luckily, bundler handled it for us so we don’t need to install 32 di
ff
erent things and hope to remember all the dependencies for our project.
That would be a nightmare.
The second thing you might notice is back in your code editor. Suddenly, there is a Gem
fi
le.lock! This is okay too - do not remove or edit it! It’s bundler’s way to ensure all
dependencies are being tracked and are part of the project. Let’s get back to writing some code now that all our pieces are in place!
22. That heavy lifting…
https://github.com/guilhermesad/rspotify
As mentioned earlier, we added a gem called rSpotify to our project. This is a great gem created to help work with the spotify API when working with Ruby projects.
The beauty of this gem isn’t just that it will make our work easier, it is that it truly exempli
fi
es the kindness of the ruby community, and open source developers in general
in that our work can be made easier because someone shouldered that burden for us. Reading through the documentation we see we will need some information to
move forward. Our Client ID and secret will be needed to authenticate. So let’s grab them from our dashboard at developers.spotify.com.
23. Do you take requests?
Before we even get the information we want, we need to authenticate. So we add the authentication information from our dashboard in the rSpotify.authenticate call as
seen here. Generally I wouldn’t share my secret, but as this is an example and the secret will be rotated before you see this, I think it’s safe.
Next we need to
fi
nd out how to call Frank to the stage. For that, we need the Spotify API documentation - which we can
fi
nd at developer.spotify.com/documentation/
web-api/
24. What’s up, Docs?
The docs can help us a long way, but we also need Spotify to get some info. Looking at the documentation console screen we see we can pull an artist. It also gives us
some great examples like what URL to Curl and di
ff
erent aspects to getting an artist, but we still need an ID.
To get Frank’s information, I simply opened spotify, went to Frank Sinatra and clicked on the 3 dots next to the follow button on his page. Here there is an option to
“Share” the artist. I copy this URL into my editor and I see a number. This is the ID for Frank Sinatra. Let me plug this into my code and leverage Spotify a bit more.
25. Let’s tune up
With our ID and secret in place we are authenticated and with Frank’s artist ID we can instantiate him as the artist variable in our code. We just need to put a few more
things in place to make this work.
First, we will need a string for the output, which I’ve cleverly called output in our example. Next we need Frank’s best tracks. Spotify will deliver the top ten, but we are
very picky and only want those top
fi
ve. Therefore, we grab the top_tracks using the RSpotify’s top_tracks module. Finally, we create an Array object (remember,
everything in Ruby is an object) and leave it empty so we can
fi
ll it.
26. Cut the tracks!
If there’s one thing Ruby does well, it’s iterate over an array. We don’t need a ton of information so we’ll just grab the names of the top tracks. After that we can iterate
over that shorter list and grab the
fi
rst
fi
ve and put them into the output for processing.
This will pass over each track and prep it for our browser. It might be good to mention the idea of DRY or don’t repeat yourself. This is a big concept in the Ruby
community and generally it’s something live by, but we can always dry things up later.
27. Somewhere to go
Once our info is processed it needs a place to go. In Sinatra, as in Rails, this means we need a view. So we’ll create a folder called view in our application and add a
fi
le
called index.erb
Here we can combine our Ruby elements with some simple HTML elements to create a view to display our results.
28. Pass it around
Finally, back in our top_
fi
ve.rb
fi
le, we will add a line to kick the output to the index.erb
fi
le. Not so dry, but we have everything we need all in about four
fi
les and maybe a
total of 50 lines of code between our top
fi
ve rb
fi
le and our index.erb
fi
le.
Time to run it and see our results. Again, we head to the command line and enter ‘ruby top_
fi
ve.rb’ then head to the browser
29. He ain’t heavy…
Voila! Simple, easy, straightforward. Not too much coding needed and we have the exact result we want. Now we can clean up our code and maybe add some style so
our
fi
nal report looks great, but this was all that was necessary.
Had this been a rails project, we’d still be bike shedding on gem sets and
fl
avors of javascript for the UI. There is too much for a simple project. That said, Sinatra has a
few caveats when it comes to it’s use as well.
30. Some drawbacks
To be fair, everything has its drawback and nothing is perfect.
With Sinatra, it’s already been said - lightweight. For a larger scale web application, Sinatra will not be what you want. It’s really for applications dealing with fewer
endpoints and few or not frequent or concurrent users. Sinatra will crash if put under too heavy a load.
That, and as it is compatible with Rails components like ActiveRecord, as your application grows, you may end up with half of Rails revisited - spawning the need for
converting it to a Rails application. While not di
ffi
cult, a little foresight may have been helpful in avoiding just that.
So, Sinatra is small, but good for some things, just not everything.
31. WARNING
https://github.com/rubylibs/almost-sinatra
When looking for Sinatra and it’s documentation, do not get fooled by something called “Almost Sinatra”. Be it known, maintainer Konstantin Hasse is a bit of a joker and
his sense of humor lead him to attempt a rewrite of Sinatra in just six lines. To say it is unsafe but functional would probably be the best quote. For a laugh though….feel
free to checkout the repo
32. Conclusions
https://github.com/aspleenic/
fi
nding_frank
The idea here is returning to a basic coding concept, keep it simple, can often lead to great results. In this case, using a great API like the one Spotify o
ff
ers, with a
lightweight framework like Sinatra and the joyful language that is Ruby, we can create something useful with less work.