top of page



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:

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.

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.

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 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:

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:

Now I got this as the Response:

[{"id":377,"type":"programming","setup":"Knock-knock.","punchline":"A race condition. Who is there?"}]