Open up your favorite browser and google itunes search api.

This is the API this first linked here

that we're going to be using to build our app.

The iTunes Search API is great,

in that we can do a lot with it, without having to authenticate ourselves.

Most robust music APIs like Spotify for example,

require you to authenticate each user and that's a bit advanced for us right now,

so we're going to be using public data provided by iTunes.

The downside though, is that this documentation for

the iTunes Search API is somewhat lacking.

Let's start at the very top-ish, at this section marked Searching.

First things first,

the documentation specifies that the data is returned as a JSON Object.

Well, good thing we know how to work with that already.

But how do we get this JSON data itself?

If you read on, it says right here that we need

to use a fully-qualified URL that fits the following format.

Now, it's not listed here specifically, but in this URL,

itunes.apple.com, this bit right here, is the base URL that we need to use.

Search is a path on the base URL that provides access to the Search API.

We call this an endpoint.

So iTunes.apple.com/search is the search endpoint.

In addition to search, we're going to be accessing another endpoint, lookup.

But we'll get to that in a second.

The last time, we created a URL to get JSON data.

All that we had a single URL with a base and a path to get that data.

Very few end points work that way, though, and in most APIs, the way that you

access certain information is by providing a set of parameters as part of the URL.

The server then reads these parameters and

creates the data set that we're looking for to return as JSON.

In the URL format specified, you'll see that after this search keyword,

there's a question mark, after which it says parameter key value.

Now this doesn't mean we write out that word.

What it means that is to construct a fully-qualified URL,

we need to include relevant parameters.

Parameters in a URL are specified as key value pairs, and

allow us to specify explicitly the type of data that we want.

The way you write out these parameters in the URL is very important, and

there's a bit of work that goes into it, but let's assume we know that for now.

Scroll down right after the search section and you should see a table.

This table defines the different parameter keys and

values that we can specify to search for different types of content.

So the first parameter key listed here is called term.

When we searched through the API, we need to provide some search terms,

much like you do when using a search engine.

Let's say we wanted to look up music for the patron saint of swift, Taylor Swift.

The search term here Would be Taylor Swift or TaylorSwift,

depending on what you type.

So to tell the server that's what we want, we include a parameter in our URL with

the key specified as term since this is defined in the documentation.

And the search term,

the actual search term that we're looking for as a value to this key value pair.

But it's not that straightforward.

If I were a user with malicious intentions, for example,

I could include some Swift code or whatever language the server is in,

let's say JavaScript, as the value for the key term in this key value pair.

My hope here is that the server would then run my code and I could wreak havoc.

This is called code injection.

To prevent things like this from happening we need to encode any value

passed in as the value to this parameter key value pair.

So if you look at the description here under values for the term, key,

you'll see that it specifies that the value should be URL encoded.

Now again we're gonna ignore this for just a little bit and

we'll cover this one we're done with our initial set up.

Other parameters include the country code for

the store you want to search if you want to limit the results for

specific countries, the media type you want to search and so on.

Now we're going to be restricting the media type to music for

the scope of this app.

But we're going to attempt to design it in a way that if you wanted to modify

the app to search for movies, it'll be pretty easy.

The next parameter in the list is called entity.

Once we strict the media type, we want to search for let's say music,

there still a broad range of types of results that we could get back.

So let's say that we type Taylor Swift and specify using a key value parameter

that the media type here that we want is music.

The results could still include the artists, tracks

any tracks with the words with Taylor or Swift are in the name, or similarly any

albums that contains those words in the title, music videos, songs and so on.

So first off, to model all that this course would be like 19 hours long.

And second, we'd have to create models that could accommodate for

all these different kinds of media.

Using the entity parameter though, we can restrict our entities to the very specific

kinds and you'll see here for music you can restrict it to this list.

For example, musicArtist, music rack, musicVideo or albums only.

The entity you specify is relative to the media type selected.

So, if we're to specify that the media type was podcast,

we could not then specify that the entity is musicArtist.

If you did do that, the server would return an error.

To prevent these kinds of simple errors from occurring,

we're going to try and define our URL creation

code in a way that doesn't allow us to create these mis-matches.

After entity, the next important parameter is attribute.

Just as entity restricts the resulting data set,

the attribute specifies the attribute we want to search for in the store,

therefore restricting our search even further.

This is easy to understand.

For example, let's say when we search through music, we

only want to search through album titles using our keywords or through artists.

As the example in here states, with the keyword Maroon 5,

we can restrict our search to only match artists with that name, rather

than all artists who have ever recorded a song with the word maroon in the title.

Also, just like Entity,

the attributes we specify are relative to the media type selected.

So you can not specify actor term as the attribute when searching through music for

example since that only applies to movies.

These third column in this table use the most important part of constructing

the URL, and that is whether the parameter is required or not.

So up at the top of the table, you should see that the search term and

country are required, but everything else is optional.

Although to be honest, when I'm constructing my URLs,

I'm going to omit the country code, as you will see, and it works perfectly fine.

So really, we don't have to bother with media, entity, and attribute.

But we will, because for starters, excluding those means that the resulting

dataset will include products from the iTunes Store, the App Store,

the iBook Store, and the Mac App Store and we don't want to parse all of that.

But more importantly, by including these additional attributes, we can take a look

at how we can construct a complex URL in code without leaving any room for errors.

Okay, so

that is a bit of information about how we interact with the search part of the API.

We're going to interact with another endpoint.

But before we get to that, how do we know what kind of data we get back by

interacting with the search part, using all these parameters, key and value pairs?

Now, this is where the documentation is lacking.

So if you scroll all the way down, right after this look up examples,

there's a section called understanding search results.

And here there's an example of a JSON response that we could get back and

right below that is a description of the values, the keys and

values that you get in this response, over here in the table.

Unfortunately though, this is only for the sample provided, so

this table does not contain descriptions about every possible key value pair.

We need some more information and for

that we need to interact with the API directly and inspect responses.

But that's not easy, right?

I mean accessing the network, constructing a URL properly with encoded parameters and

inspecting the JSON result, that's like 80% of the work in this course.

Thankfully there're great tools that we can use to make this initial step easier.

Let's check it out in the next video.