Re: Some Slides which contain my Observations and Insights about REST

Hi David,

Wow this is some _outstanding_ feedback -- many thanks!

On 01/14/2015 08:16 PM, David Booth wrote:
> Hi Thomas,
>
> Regarding
> http://vanthome.github.io/rest-api-essay-presentation/rest_apis.html
> Very nice material!  And a very nice progression through REST, some 
> semantic web concepts, JSON-LD and Hydra.  I really like the line of 
> thinking.

Yea, It took me really weeks to flesh out this "read thread" as we 
say... it would not have been the same if I had hacked it together in 
three subsequent days.

>
> A few comments and small suggestions:
>
>  - I would suggest slightly shortening the semantic web section, since 
> it introduces several concepts and terms that are not really used 
> further in the slides.  This might sound like a strange suggestion 
> coming from a semantic web-head like me, :)  but I think one of the 
> nice things about JSON-LD is that programmers do not have to be 
> exposed to so much semantic web detail when using JSON-LD.

ok, I think about shortening this or packing it in reveal and use a y-axis.

>
>  - If possible, I would suggest adding a small, simple REST example, 
> perhaps even showing "DO"s and "DON'T"s.  For example, show what it 
> means to have the server return a set of links for the possible client 
> next steps, as opposed to having a fixed URL pattern.  Programmers 
> hear abstract platitudes REST all the time -- what it is and isn't -- 
> but they need to know concretely (through simple examples) how to do 
> REST properly.
yea, this needs to be stressed more. I added a todo to add more examples 
to the hydra section [1].

>
>  - On slide 4, I am slightly uncomfortable with the emphasis on APIs, 
> because I fundamentally think we need to get away from the API focus 
> and focus on what really matters: THE DATA.  APIs are necessary --  we 
> *need* APIs.  But we do *not* need a plethora of different APIs.  We 
> should just use REST, be done with that discussion, and move on to the 
> more important matter of THE DATA. (Or, if for some reason someone 
> forces you to use something other than REST for a project, then 
> gracefully register your disagreement, and move on to the more 
> important issue of THE DATA.)  My concern is that if we focus too much 
> on APIs then we are likely ignoring what's *really* important, which 
> is THE DATA. I say this in the same spirit as I say that we should not 
> be focusing on data formats, we need to focus on the *semantics* of 
> data. (Certainly we need data formats, but a data format in and of 
> itself does not solve the problem of semantic interoperability. Data 
> formats allow bits to be transferred, but more importantly they should 
> provide a hook for determining data semantics, and this is what really 
> matters.)  In short, I do not disagree with your statement about the 
> importance of offering an API, and I certainly agree that the API of 
> choice is REST, but I am just slightly concerned that if we talk too 
> much about APIs we may be losing sight of the most important thing: 
> THE DATA.
I can follow you here, ultimately we want to achieve this state where 
"the Web is more than the sum of its elements"; where you don't need to 
fire up a Web browser yourself to book a flight because an agent will 
find and book the best one for you (just some musing).
The main enablers for this are the _interface_ (REST API) and of course 
the _data_. But as the focus of this presentation lies on the former 
(the interface) I don't want to overwhelm people with another aspect. I 
want to present this to give people my vision about the interface 
problem and I think there are some slides where the broad-minded reader 
will also take away that as a side effect of doing APIs like this, he 
gains a lot in terms of data modelling.

>
>  - On slide 9 it seems strange to see JavaScript in the same category 
> as REST, SOAP and XML-RPC, since JavaScript is a programming language, 
> not an API.  I think it would be good to clarify what you mean by 
> JavaScript as an API.
Yea I also don't like this but this is a chart from some article [1] I 
took over because it is the most recent I could find.
Probably they have it because there are still many APIs only through 
some SDK and not the real API and often times, this SDK is a JS one.

>
>  - I was surprised on slide 18 to see:
> "Individual resources are identifiable with a GUID".  For REST (and 
> the web in general) I think that should be: "Individual resources are 
> identifiable with a URI (or IRI)".

Yea that was because up to this point I want to speak in terms of the 
stipulations of Fielding's manifesto in "5.2.1.1 Resources and Resource 
Identifiers" does not speak about URIs or IRIs (which were not existing 
in 2000, I know)
The section just requires you to have "... a resource identifier to 
identify the particular resource involved in an interaction between 
components". So in general you would use some globally unique identifier 
to follow this stipulation.
Of course I propose to use IRIs, on slide 35:
“Resource”: A uniquely identifiable thing, typically identified by an IRI.

>
>  - On slide 15: Where it says "It's not a protocol or about a single 
> protocol (HTTP)" I think it would be clearer to say "It's not a 
> *transport* protocol or about a single *transport* protocol (HTTP)", 
> because in a very broad sense REST *is* a kind of protocol -- it says 
> who should do what -- but it isn't a protocol in the sense that I 
> think you meant.
>
>  - On Slide 35, a small correction: in RDF 1.1 literals are now 
> *always* typed (defaulting to xsd:string).  In Turtle, "foo" and 
> "foo"^^xsd:string both have type xsd:string.
So right! Corrected it and moved text localization to a separate slide.
>
>  - On slide 40, it would be good to reference the W3C Linked Data 
> Glossary:
> http://www.w3.org/TR/ld-glossary/#linked-data
how could I miss that! I even know and like it.
>
>  - You might be interested to look at the paper on "RDF and SOA" that 
> I wrote in 2007:
> http://dbooth.org/2007/rdf-and-soa/rdf-and-soa-paper.htm
> That was written long before JSON-LD existed, when SOA and SOAP were 
> still being hyped a lot, and REST was not yet so widely recognized as 
> superior (in general) to the WS*/SOA/XML/SOAP approach, but it 
> provides a view of how RDF (and now JSON-LD by extension) can be used 
> to great advantage in a RESTful or SOA style of interaction.  I think 
> it is very much in accordance with the RESTful, JSON-LD-based style 
> that you are advocating.

I read through it;

I like your rationale why RDF also adds value if its used as data model 
for applications.
Also, this "Babelization" issue you mention is a good point.
I added a slide "What we gain from using RDF" to highlight these.
>
> Typos:
> s/kicked of/kicked off/
> s/syntactucally/syntactically/
> s/acomplish/accomplish/
> s/What do pseudo REST APIs wrong/What do pseudo REST APIs do wrong/
> s/at least on/at least one/
> s/tings/things/
> s/JSON0-LD/JSON-LD/

merged :)

[1] https://github.com/vanthome/rest-api-essay-presentation/issues/3
[2] http://www.bogotobogo.com/WebTechnologies/OpenAPI_RESTful.php

>
> Thanks!
> David Booth
>
> On 01/14/2015 04:07 AM, Thomas Hoppe wrote:
>> Funny :)
>> Actually I was really searching hard for this because it bugged me to
>> have no reference.
>> I remember that I found some stuff but only that within mainframe 
>> systems,
>> MQ was/ is the dominant integration vehicle and knowing that mainframes
>> happened
>> before RPC I deduced this.
>>
>> On 01/14/2015 08:59 AM, Sebastien Lambla wrote:
>>> Curioisity item. I was writing a chapter for my book on the same 
>>> intro you just did. Do you have any reference material for how MQ 
>>> appareared before RPC?
>>>
>>>
>>>> On 14 Jan 2015, at 07:45, Thomas Hoppe<thomas.hoppe@n-fuse.de>  wrote:
>>>>
>>>> Hi,
>>>>
>>>> sorry maybe it's too unrelated for this list but I hope that some 
>>>> of you might find this useful.
>>>> I have compiled my (highly opinionated) observations in some slides 
>>>> [1] to give people
>>>> (especially with enterprise background) a big picture about what 
>>>> REST is,
>>>> why it is relevant and how Hydra and JSON-LD help us making the 
>>>> step to the Web 3.0.
>>>>
>>>> [1]http://vanthome.github.io/rest-api-essay-presentation/rest_apis.html 
>>>>
>>>>
>>>> Greets, Thomas
>>>>
>>>>
>>>>
>>

Received on Thursday, 15 January 2015 10:29:32 UTC