Introduction to OData
OData, or the Open Data Protocol, is a standard protocol for communication with data APIs. It builds off of standard protocols, technologies, and accepted methodologies such as HTTP, JSON and REST to allow applications to query & consume data API endpoints without requiring cumbersome serverside libraries; while a variety of libraries exist to make consuming OData-based APIs even easier, you could interact with an OData-powered API over REST-like HTTP entirely by hand, if you wanted to.
You can find more information about OData at the OData project site located at http://www.odata.org.
Core OData Concepts
OData endpoints expose feeds, which are collections, of entries of a specific type which in turn contain parameters/information. You can then filter these collections using a variety of query parameters in the URL to narrow down the scope of what you'd like returned. To put this in concrete terms, our Media() endpoint exposes all of our tracks. If you were to query it with no additional query parameters, it would be like asking us for all of the 10MM+ tracks we have — probably not what you want, and definitely not what we'd want to serve, so we limit the amount of results returned with a "raw" query like this to a single entry. To narrow down your results, you can specify keywords to search against; more complex query filters for things like content in a specific genre or available in a specific country; as well as specify a starting index and limit the number returned for pagination purposes.
So, given the base URL of https://search.mcnemanager.com/current/content.odata/, the Media collection's base URL would be https://search.mcnemanager.com/current/content.odata/Media()/. Valid collections are Albums(), Artists(), and Media().
This is further explained in-detail in each section of the documentation for each particular endpoint, but throughout the documentation you'll see the Demo Widget like the one below which will let you use your system credentials to generate sample requests and immediately see the generated Rhymba URL as well as the data returned.
A Collection? What If I Want a Single, Specific Piece of Content?
If you know the ID of the specific piece of content you'd like, you don't have to fiddle with keywords, $filters, and other parameters (all of which are described below and in other parts of this documentation); you can simply retrieve the content directly by including its ID in the parentheses for the collection. In other words, https://search.mcnemanager.com/current/content.odata/Album(12345)/ would retrieve details on album ID 12345. You can then use the $select query parameter, described below, to only return the properties you're interested in.
OData exposes a $filter keyword in URLs for more powerful querying capabilities. We'll cover this in the Search part of the documentation, but basically $filter map a SQL-similar query approach to OData URLs, allowing you to look up specific fields by name that equal (or don't equal, or contain) parameters. This is advanced usage, however, and it's difficult for us to optimize all the various ways you can do a custom $filter, so we try to have most common use cases be serviced via custom query parameters.
All String data in OData must be contained in single quotation marks. This may require url encoding them to %27. If you need to escape an apostrophe, this is done by adding a second consecutive apostrophe.
Let's generate your first Rhymba API call. In the example widget below, just input your API access token and press Run Example to see what Rhymba returns. (If you have cookies enabled, we'll then store your access token in a cookie so you don't have to enter it on every example.)
Let's walk through the basics of what's happening here. More details are available in the documentation on Search.
Looking at the URL that's being called reveals a lot of information. That URL is: https://search.mcnemanager.com/current/content.odata/Media()/?$format=json&keyword=''&$skip=0&$top=10&$select=id,title,album_name,album_artist_name&access_token=. Let's take each part piece-by-piece.
search.mcnemanager.com/current/content.odata/ is the base URL for the Rhymba search API. The /current in the URL allows you to target different versions of Rhymba; /current will always point at the most current production release. As time goes on, you may choose to stay on a particular release version number, but /current will always have the most recent bug fixes and functionality enhancements, and we recommend it for most applications.
Next up you specify which collection you're going to be querying against. In the example URL above, Media()/ means you're hitting our collection of media/tracks. As you can see, the collection is a part of the URL path. You can find detailed information on the Media collection in the Search section for it. But, basically, you're looking for media that meets certain criteria you're going to specify shortly. Media, like all content, is subject to whitelisting rules regarding what content & providers your service is able to see through our APIs.
Next, we get to the "meat" of your query. We've implemented a helper query parameter called keyword, in this case keyword=''. What the keyword parameter does when used against the search.mcnemanager.com/current/content.odata/ API is a bit of an "intelligent" search across several different fields in our index. It's almost always preferable to use keyword when searching for content by name, rather than implementing your own text search via OData's $filter query parameter, but we'll still discuss $filter at a later point. Also, please note that, unlike other standard OData query parameters, keyword does not use the $ prefix. That's because this is a custom query parameter.
You obviously don't want to receive everything that matches your query; doing so ends up with a huge amount of unnecessary data being sent over the wire to your application. So, we implemented the $skip and $top query parameters. $skip=0 translates to "start at the beginning", as the collection indexes are zero-based, and $top=10 means "give me 10 results". If you're implementing pagination, which you likely will be in most circumstances excluding "find-as-the-user-types", this would be like the first page of results. To retrieve the second page of results, you'd then specify $skip=10&$top=10 on a subsequent query. We also have a parameter that will give you the total count of results returned by your query, without requiring you to retrieve all of the results, so that you know how many pages of results you've got.
Likewise, you probably don't always want every piece of metadata we have on the content you're querying. Maybe you just want the various IDs, titles/names, and price. Or maybe not even that. To that end, you specify which properties of the content you want to get back using the $select query parameter. In our example above, we're asking for id,title,album_name,album_artist_name; since we're querying against Media(), this means we're getting back the media/track's unique ID, the song title, the album_name of the album this track is on, and album_artist_name, or the name of the artist for the album.
Finally, you specify your system- or application-specific access_token. In some non-search requests such as purchases and downloads, you'll have to include additional information to validate and verify your requests. But, those will be covered in each relevant section.
Also, please note that the query parameters can usually be specified in any order you'd like. It's best to standardize them, however, to make your development process as painless as possible. Like a regular query string, you always must begin the query parameter collection in the URL with ?, and each parameter is separated by an ampersand, &. If you need to use an ampersand as a part of the keyword, you should escape it to its HTML entity.
Got All That?
Whew, that was a lot of info. At this point, you actually already have enough of the basics to start getting started with our Search APIs, but don't worry: we cover this much more in-depth — as well as advanced topics such as custom $filter usage for things like genre- and geographic-based lookups — as you go through the sections of documentation.