Vocabulary content negotiation

[sgoto]

Hey all,

   Just wondering: have you ever had to provide multiple vocabulary options to your API clients? And if so, how did you accomplish that?

   Context: one of the challenges that I face, as a consumer of a large number of APIs (think "thousands"), is that I can't afford to "manually" read/understand a large number of vocabularies.

   So, wondering, as HTTP offers ways to negotiate content types with things like Accepts and Content-Type (e.g. Accept-Language, Accept-Encoding,, etc), has anyone ever provided an API that would accept something like an Accept-Vocabulary header that converts things into potentially client-supported vocabularies?

   I'm thinking it would go something like this. This is what your API would look like today:

GET /mountain-view HTTP/1.1

Host: api.yellowcab.com

   This is what you'd typically get (which clients have to manually understand your custom vocabulary):

HTTP/1.1 200 OK

Content-Type: application/json+ld

{

  name: "Sam",

  lastName: "Goto"

}

  But, with the help of some extra headers, you'd ask the server to translate their custom vocabulary into something that the client could understand:

GET /mountain-view HTTP/1.1

Host: api.yellowcab.com

Accept-Vocabulary: http://schema.org

  Responds:

HTTP/1.1 200 OK

Content-Type: application/json+ld

Content-Vocabulary: http://schema.org

{

  @context: http://schema.org,

  @type: Person,

  givenName: "Sam",

  familyName: "Goto"

}

   That allows generic hypermedia clients to be written that understands some of the common vocabularies and connect to arbitrarily APIs without re-compilation (http://opg.me, http://microformats.org, http://activitystrea.ms, http://schema.org, etc -- add your favorite).

   Anyone ran into this before? Ideas on how it was solve historically? Other options/alternatives I should consider?

   Sam

--

f u cn rd ths u cn b a gd prgmr !

[mca]

i like the idea of separating semantics from format and protocol. that's one of the principles Leonard and I talk about in the RESTFul Web APIs book.

adding semantic/vocabulary negotiation is an interesting idea, too. the examples you give here are, IIUYC, negotiating the *format* for carrying semantics, not the actual semantics, right?  i think that can be handled via conneg (we are talking about formats) already, tho.

am i missing something? 

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Mike Kelly]

Hi Sam,

I'm wondering, if you can't afford to manually read/understand the contents of the messages, how can you afford to retrospectively amend thousands of APIs to:

1. use this new kind of vocab negotiation

2. produce the necessary mappings from the existing data to each of the required vocabs

that seems like a lot more work than the manual read option.

Cheers,

M

--

You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

--

Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[sgoto]

On Wed, Jul 22, 2015 at 10:57 AM, mca <m...@amundsen.com> wrote:

i like the idea of separating semantics from format and protocol. that's one of the principles Leonard and I talk about in the RESTFul Web APIs book.

adding semantic/vocabulary negotiation is an interesting idea, too. the examples you give here are, IIUYC, negotiating the *format* for carrying semantics, not the actual semantics, right?  i think that can be handled via conneg (we are talking about formats) already, tho.

am i missing something? 

No, I was referring to the actual application/domain-specific semantics. Maybe we are having a "vocabulary-mismatch", but I'm referring to the domain-specific semantics (e.g. what words you use to describe "a person, a watercooler, a swimming pool, a newpaper, etc").

For example, suppose this is YOUR API (and let me fix the "structural semantics" in JSON-LD) and you represent a "book" using your OWN words:

{

  @context: "http://mca.com",

  @type: Book,

  canonicalBookNumberId: "ISBN1234",

}

That would make perfect sense for you and your clients, but it requires your clients to understand your specific vocabulary.

If, however, you had the interest to "speak somebody else's language", say, a different "vocabulary" to "express the same ideas", maybe your clients could ask your API:

"hey, perhaps you could re-write your payload under my own terms? for example, i understand http://schema.org/Book and its properties, as well as opengraph's Books representation"

and you'd go like

"oh, yeah, that's totally cool. here, take it in opengraph:"

{

  @context: "http://ogp.me",

  @type: Book,

  "book:isbn": "ISBN1234",

}

or

{

  @context: "http://schema.org",

  @type: Book,

  isbn: "ISBN1234",

}

Does that clarify what I was referring to?

[sgoto]

On Thu, Jul 23, 2015 at 4:28 PM, sgoto <samue...@gmail.com> wrote:

On Wed, Jul 22, 2015 at 10:57 AM, mca <m...@amundsen.com> wrote:

i like the idea of separating semantics from format and protocol. that's one of the principles Leonard and I talk about in the RESTFul Web APIs book.

adding semantic/vocabulary negotiation is an interesting idea, too. the examples you give here are, IIUYC, negotiating the *format* for carrying semantics, not the actual semantics, right?  i think that can be handled via conneg (we are talking about formats) already, tho.

am i missing something? 

No, I was referring to the actual application/domain-specific semantics. Maybe we are having a "vocabulary-mismatch", but I'm referring to the domain-specific semantics (e.g. what words you use to describe "a person, a watercooler, a swimming pool, a newpaper, etc").

For example, suppose this is YOUR API (and let me fix the "structural semantics" in JSON-LD) and you represent a "book" using your OWN words:

{

  @context: "http://mca.com",

  @type: Book,

  canonicalBookNumberId: "ISBN1234",

}

That would make perfect sense for you and your clients, but it requires your clients to understand your specific vocabulary.

If, however, you had the interest to "speak somebody else's language", say, a different "vocabulary" to "express the same ideas", maybe your clients could ask your API:

"hey, perhaps you could re-write your payload under my own terms? for example, i understand http://schema.org/Book and its properties, as well as opengraph's Books representation"

ah, forgot to add the opengraph definition of a book:

https://developers.facebook.com/docs/reference/opengraph/object-type/books.book

[sgoto]

Hi Mike,

   Great question! Thanks for asking!

On Wed, Jul 22, 2015 at 12:19 PM, Mike Kelly <mikeke...@gmail.com> wrote:

Hi Sam,

I'm wondering, if you can't afford to manually read/understand the contents of the messages, how can you afford to retrospectively amend thousands of APIs to:

1. use this new kind of vocab negotiation

2. produce the necessary mappings from the existing data to each of the required vocabs

that seems like a lot more work than the manual read option.

I think the short answer is that I hope I won't be alone asking for interoperability. I hope that more folks would want to make their APIs interoperate using fewer of the-same-words-that-describe-the-same-things.

More importantly, I think that's also "the right thing to do". The "manual read option" requires me to "manually select" which people I want to work with and I don't think that's fair (or good) for an ecosystem. I think it is important to give *everybody* the *ability* to join my system if they choose to (as opposed to "myself manually selecting" who I work with).

I also think it is my job to provide the *incentives* for someone to join my system, but that's an orthogonal question to providing the *ability*.

Ultimately, I'm converging to that having already tried the "manual read option" and realizing that it doesn't scale. I go over some of my personal story and attempts here if you are curious.

[Mike Kelly]

On Fri, Jul 24, 2015 at 12:37 AM, sgoto <samue...@gmail.com> wrote:

Hi Mike,

   Great question! Thanks for asking!

On Wed, Jul 22, 2015 at 12:19 PM, Mike Kelly <mikeke...@gmail.com> wrote:

Hi Sam,

I'm wondering, if you can't afford to manually read/understand the contents of the messages, how can you afford to retrospectively amend thousands of APIs to:

1. use this new kind of vocab negotiation

2. produce the necessary mappings from the existing data to each of the required vocabs

that seems like a lot more work than the manual read option.

I think the short answer is that I hope I won't be alone asking for interoperability. I hope that more folks would want to make their APIs interoperate using fewer of the-same-words-that-describe-the-same-things.

More importantly, I think that's also "the right thing to do". The "manual read option" requires me to "manually select" which people I want to work with and I don't think that's fair (or good) for an ecosystem. I think it is important to give *everybody* the *ability* to join my system if they choose to (as opposed to "myself manually selecting" who I work with).

I also think it is my job to provide the *incentives* for someone to join my system, but that's an orthogonal question to providing the *ability*.

Seems like this is a typical chicken-and-egg problem. Can you be more specific about what those incentives are or might be?

Cheers,

M

[sgoto]

That's a great and tough question, and one that I'm learning/adapting as I go.

In my experience, I think conversions/traffic is looking like a reasonable starting point.

For example, things like [book a table at cascal] are now possible and beneficial to all parties involved: users, API providers, merchants and search engines.

For email clients, things like [RSVP-ing to events] are now possible and also beneficial to all parties.

I agree with the chicken-and-egg problem, but if you create something like this as a  "chicken", it does seem like 650K sites would be interested in investing in an "egg".

Interoperability matters.

 

Cheers,

M

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.