Thoughts about the client API ...

Hi!

I followed the discussion on the other mailing list and I hope that some
persons from there will read here as well.

I must confess, that I don't know what "HATEOS" and several other things
are that are discussed on that list - but I worked with several APIs
(app.net, Twitter, pump.io, Facebook, status.net, Tumblr, ...) when
writing and improving connectors for Friendica.

I see the problem that the whole stuff shouldn't be too complex. I
really like APIs with defined URI patterns. They make programming much
easier. I do not really see the problem that hardcoded patterns could
interfere with other stuff. You could easily avoid that by defining a
flexible API starting point.

Programmers are lazy people. They will rather have a look at the
examples than reading hundreds of pages full of abstract stuff. If easy
things like creating and reading posts from a mobile client results in
too much preparations (like reading and interpreting a "machine
readable" description of the API) they won't do that, I guess. They
would maybe have a look at their favourite server and would test against
that, hoping that this would work on other systems as well. (Just think
of the many systems that even had hardcoded "identi.ca" in the API calls
as hostname)

I'm totally with Evan concerning these points in the discussion.

Having a strict URI pattern has another advantage as well: It is easier
to implement for server programmers since they hadn't to think about a
pattern on their own - which could easily result in

Additionally I really don't like systems where I have to do several API
calls for a single task. If I want to fetch my timeline I want to do
that with a single request. If I want to post an item then I want to do
a single post call.

BTW: I'm a huge fan of the API of app.net:
https://developers.app.net/reference/resources/

It is a clear structure, it's mighty and extensible. The annotations are
a great concept to deliver content that is maybe specific to only a few
installations. See here:
https://developers.app.net/reference/meta/annotations/

An example for annotations: Pump.io is using HTML as message format,
Diaspora is using Markdown, Friendica is using BBCode. HTML should be
the standard, but in annotations you could delivery the bbcode or the
markdown *additionally* to the HTML to avoid transformation problems
when delivering content between the servers.

Michael

Received on Thursday, 29 January 2015 08:07:01 UTC