Question

I have the base URL for a RESTful API. I have a list of some of the resources types that it provides. like:

GET http://www.baseURL.com:8180/fruits

will result in something like:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <FruitList xmlns="http://www.baseURL.com/Fruits">
  <Fruit>
    <Identity createdTimeStamp="2011-05-13T09:45:16.611-05:00" lastUpdatedTimeStamp="2012-11-19T03:24:19.310-06:00">
        <FruitName>Apple</FruitName>
    </Identity>
  </Fruit>
  <Fruit>
    <Identity createdTimeStamp="2011-05-13T09:45:17.241-05:00" lastUpdatedTimeStamp="2012-11-19T03:24:20.431-06:00">
      <FruitName>Banana</FruitName>
    </Identity>
  </Fruit>
  <Fruit>
    <Identity createdTimeStamp="2011-05-13T09:45:19.445-05:00" lastUpdatedTimeStamp="2012-11-19T03:24:21.281-06:00">
      <FruitName>Orange</FruitName>
    </Identity>
</Fruit>
</FruitList>

Is there a way that if I didn’t know that this API had ‘fruits’ as a resource that I could figure that out by some type of generic GET command?

Answer 1

All communication requires some advance knowledge, RESTful APIs included. If I say “Hello” and you only speak Klingon, you might think I was insulting you. The pre-supposed knowledge required for a RESTful API includes:

• The entry point (a URL)
• Knowledge the interface and how to use it effectively (i.e. HTTP methods and return codes — see REST API – why use PUT DELETE POST GET? for more)
• What representation formats can be reasonably expected to be available
• An understanding of the semantics of those formats

These should be documented so that client authors can make use of them. It therefore makes sense to re-use existing specifications wherever possible, rather than invent new ones. Doing so means existing clients can understand much or all of your API without even having seen any documentation for it. This is how new web sites can be added to the internet without browser vendors having to go back and update their browser to access the new web site.

For example in HTML:

entry point = http://www.example.com/
hypertext formats expected = HTML, XHTML, SVG, etc.

a modern browser knows the semantics of each of those, so when it encounters in a HTML response the text

<link rel="stylesheet" href="/style.css">

it will know that the LINK element represents a hypermedia pathway, and the relationship of the resource is that of the “stylesheet” relation, which it understands to have certain effects (namely, restyling the presentation of the primary response).

Your API should have at its base URL, http://www.baseURL.com:8180/, a set of hypermedia links to resources it provides, <a href="/fruits">Fruits</a>, which can be followed by any client that understands HTML. If you want to add meaning to those links, you need to provide a relationship. There already exists a list of pre-defined link relations but if none of those suit you, you could either look for suitable relationships defined in other public ontologies, or define your own, using URIs within a namespace you control. It is recommended to use dereferencable HTTP URLs which provide human-readable documentation. For example:

rel="http://www.baseURL.com:8180/documentation/#FruitList"

So, in direct answer to your question,

Is there a way that if I didn’t know that this API had ‘fruits’ as a resource that I could figure that out by some type of generic GET command?

your client needs to GET the entry URL to the API, look at the relationship provided for each link, and know what that means because it is pre-defined somewhere and the client has knowledge of what a FruitList means to the user.