2

I just finished reading REST in Practice as my first* introduction to REST APIs. I found the book quite enlightening, but am left with one nagging question, and Google has yet to clear it up. This question gets close, but the answers fall short of answering my specific question, which is...

Given some hypertext markup for consumption with a RESTful API, such as this (in JSON-LD):

{
  "http://schema.org/name": "Manu Sporny",
  "http://schema.org/url": { "@id": "http://manu.sporny.org/" },
  "http://schema.org/image": { "@id": "http://manu.sporny.org/images/manu.png" }
}

What is the function of the URL/URI/IRI as a "key" name? (Now I know that JSON-LD--with @context--and other markup languages, allow ways to generalize these IRIs-as-keys to be more human friendly, but that doesn't change the nature of the question.)

If I try to break my question down into smaller pieces, I come up with something like this:

  • Specifically, what is expected to live at the endpoint represented by that IRI?
  • All the discussion talks about disambiguating key names. But how is http://schema.org/name less ambiguous than name?
  • Is there some (theoretical?) centralized repository of key types that developers are expected to reference, so that these key names all point to some more-or-less common definition?

I hope this question makes enough sense to be answerable. I'm still in a bit of a "I don't know enough to ask what I don't know" state on this particular point.

*I, like many, thought I already knew what REST was, and believed that my previous, POST-only CGI scripts were representative of REST APIs...

Flimzy
  • 704
  • 4
  • 13

2 Answers2

2

what is expected to live at the endpoint represented by that URI?

A resource of some kind. Generally, you can identify the type of resource by examining the mime type. Often, it's just a web page.

How is http://schema.org/name less ambiguous than name?

It lives specifically at the http://schema.org/ domain, and the domain itself is unique. In other words, the domain name provides the disambiguation.

Is there some (theoretical?) centralized repository of key types that developers are expected to reference, so that these key names all point to some more-or-less common definition?

ICANN.

Robert Harvey
  • 198,589
  • 55
  • 464
  • 673
  • `A resource of some kind.` -- What kind of resource? A human-readable resource that says "a word or phrase that refers to or that can refer to a specific person"? Or something machine-readable? Or...? I guess in other words, does this resource tell a developer how to use the data, or does it tell a program how to use the data? – Flimzy Apr 23 '15 at 17:25
  • A resource should have a content-type. The content type spec tells both the developer and the program how to use the data. For example HTML 5 spec tells a web browser how they should interpret a html document, which ultimately leads to a browser drawing a html page (badly in the case of IE 6 :-P) – Cormac Mulhall Apr 24 '15 at 11:25
-1

What is the function of the URL/URI/IRI as a "key" name?

The answer can be found in RFC 5988 (Chapter 5.3. Relation Type):

Note that extension relation types are REQUIRED to be absolute URIs...

Simply put, the "keys" you are referring to are called "relations" and in order to be uniquely identified, you can either use any of the standardized ones (like self, author, stylesheet, etc) or you can introduce custom ones, in which case you need to namespace (prefix) them in such a way that noone else creates the same named relation that means something else. This is done by using a relation name in a form of an absolute URI, as mentioned in that RFC document.

Mladen B.
  • 129
  • 3