Understanding APIs (Part 4): What is a URI?
We are slowly starting to get a sense of what an API is. So far, we’ve been learning, piece by piece, some of the components that define an API. Let’s take a look back at what we’ve learned:
Understanding APIs (Part 1): What is an API? - We defined the 4 aspects: Inputs, Operations, Outputs, and Data Types. We also explained what an API’s Request and Response is. Finally, we put all this together in a diagram.
Understanding APIs (Part 2): API Analogies and Examples - To get a better grasp, we talked about the Restaurant and Calculator analogies. Then, we defined the Human Resources API example using the CSV and JSON Data Types.
Understanding APIs (Part 3): What are HTTP Methods? - We started getting technical and learned about the 5 most popular HTTP methods used by RESTful APIs: GET, POST, PUT, PATCH, and DELETE.
Diagram defined in Part 1, which contains the 4 aspects of the API + the Implementation.
For this post, we will learn what a URL and a URI really are and how this fits in our previously defined diagram.
What is a URL?
In the previous post, we learned that RESTful APIs or RESTful Web Services are calls that are made through HTTP (Hypertext Transfer Protocol).
When you’re using a telephone to make a call, you need to know the telephone number to dial. When you want to make a call using HTTP, you need to know the web address instead of the telephone number. This web address is known as a URL (Uniform Resource Locator). E.g. https://www.google.com.
URLs are mostly used to retrieve websites or web pages from the internet (using HTTP) such as Google or Facebook. But URLs can also be used for File Transfer (through FTP), database access (using JDBC), and many others.
What is a URI?
From Wikipedia: “The most common form of URI is the Uniform Resource Locator (URL), frequently referred to informally as a web address.”
Actually, a URL is just a form of URI (Uniform Resource Identifier). A lot of people use both terms to refer to the same thing in the API world. For the sake of this post, let’s just say that a URL is mostly used for visual websites, and we’ll be using URIs to call our APIs. E.g. https://api.twitter.com/2/tweets/:id.
Example: Joke API
I went ahead and googled some public APIs that I could use as examples, and I found this Joke API that, when called, returns with a joke in JSON format.
Official Joke API documentation is taken from the README.md file.
Since these are all using GET as the HTTP method, you can open these links directly from your browser (or just click on them).
Let’s check out the first option, which is to grab a random joke: https://official-joke-api.appspot.com/random_joke
This is what I get in my browser after clicking or inputting the link:
{"id":131,"type":"general","setup":"How do you organize a space party?","punchline":"You planet."}It may be a bit hard to read if you’re not familiar with the JSON syntax, but it basically returned a setup that says, “How do you organize a space party?” and the punchline is “You planet.”
Let’s try now to retrieve a random programming joke: https://official-joke-api.appspot.com/jokes/programming/random
Now I got this as the Response:
[{"id":377,"type":"programming","setup":"Knock-knock.","punchline":"A race condition. Who is there?"}]