API

[David Kettler]

So I just posted this to the diaspora-services group, but I know not all people interested in APIs are over there, so I've cross-posted it here.

---
Alright guys and gals, time for the first real project of this group: defining a simple, powerful, secure, open, and extensible API for Diaspora*

To keep this process moving and scale it reasonably, we'll use the following release cycle:
    1.    Discuss
    2.    Post mock version of the API for public feedback
    3.    Deploy read-only version of the API for consumption by a private alpha pool of developers
    4.    Open up the read-only API to anyone, deploy a writable version of the API to a private alpha pool of developers
    5.    Fully open the reading and writing API

We will start this process on the main 4 diaspora resources: People, Aspects, Posts, and Comments. As we wish to make other resources available, we will submit them to the same release process to ensure quality and scalability.

Now, on to the meaty stuff: where we should start with data types. Luckily, there has been a *lot* of work, both from academia and from enterprise, around defining Social APIs. The best combination of openness, comprehensiveness, and highly-adopted-ness I believe is clearly OpenSocial. As such, we should shoot for their API server spec: http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-API-Server.xml with limited modifications. Mainly, we want to be RESTful on JSON as well as XML (in fact, I'd shoot for JSON support before XML support), and I don't know if we need the RPC component. We'll mainly want to hear real-dev feedback here, as they know their apps better than we do :)

To clarify, RESTful means
to read a list, GET /plural_resource
to read an item, GET /plural_resource/id
to create an item, POST /plural_resource
to update (by replacement) a list, PUT /plural_resource
to update (by replacement) an item, PUT /plural_resource/id
to delete a list, DELETE /plural_resource
to delete an item, DELETE /plural_resource/id

the PUT/POST mapping to create/update/replace is often murky (basically, a lot of servers ignore PUT and ask that all creating/updating be done through POST)-- some input here on how by-the-books RESTful we want to be would be nice :) (check out http://stackoverflow.com/questions/630453/put-vs-post-in-rest for some discussion).

For People, we'll use Portable Contacts http://portablecontacts.net/draft-spec.html (which OpenSocial is aligned with)

For Aspects, we'll use OpenSocial Groups http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-Data.xml#Group (this may need some small modification to make them as rich as D* aspects… namely, whether or not the specified group is publicly listed or not)

For Posts, we'll go with ActivityStreams: http://activitystrea.ms/specs/json/1.0/ which has a schema defined at http://activitystrea.ms/head/activity-schema.html

For Comments, we'll also go with ActivityStreams (see http://activitystrea.ms/head/activity-schema.html#comment)


To be clear, a lot of the wording above sounds dictatorial-- I did not mean it as such, it's just way easier to type that way :) The entirety of this post is up for debate, but I hope that we'll stick to building a RESTful API based on the existing web standards surrounding social services.

Thanks,
David

[Stephie King]

David, you are the fucking man!

--
You received this message because you are subscribed to the Google Groups "diaspora-dev" group.
To view this discussion on the web visit https://groups.google.com/d/msg/diaspora-dev/-/uhTxnB5zRhIJ.
To post to this group, send email to diaspo...@googlegroups.com.
To unsubscribe from this group, send email to diaspora-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/diaspora-dev?hl=en.

[Pistos]

On Oct 13, 6:53 pm, David Kettler <21ech...@gmail.com> wrote:
> Alright guys and gals, time for the first real project of this group:
> defining a simple, powerful, secure, open, and extensible API for Diaspora*

Good show! I've already wanted to do something programmatically with
Diaspora, and was a bit disappointed to see that there wasn't any API
yet. So this initiative of yours is welcome.

> Now, on to the meaty stuff: where we should start with data types. Luckily,
> there has been a *lot* of work, both from academia and from enterprise,
> around defining Social APIs. The best combination of openness,
> comprehensiveness, and highly-adopted-ness I believe is clearly OpenSocial.

> For People, we'll use Portable Contacts

> For Aspects, we'll use OpenSocial Groups

> For Posts, we'll go with ActivityStreams

> For Comments, we'll also go with ActivityStreams

Can you tell us why we shouldn't just expose the data as a nearly
literal "to_json" translation of the objects? This seems to me the
approach which would be simplest, most straight-forward, and easiest
to understand and get started with. Having to deal with a mapping of
DB columns to RFC field names would be added mental taxation, a source
of confusion and a hindrance to learning the system and getting things
done.

> with limited modifications. Mainly, we want to be RESTful on JSON as well as
> XML (in fact, I'd shoot for JSON support before XML support), and I don't

JSON is fine with me, and I could do without any XML, but I don't see
what the big deal about REST is, personally. Having said that, I
wouldn't resist intent to adhere a little or a lot to REST.

> know if we need the RPC component. We'll mainly want to hear real-dev
> feedback here, as they know their apps better than we do :)

For my particular [first] use case, I merely want to be able to post
new messages and comments [on those messages], and all this to a
single account under my control.

> To be clear, a lot of the wording above sounds dictatorial-- I did not mean
> it as such, it's just way easier to type that way :) The entirety of this
> post is up for debate, but I hope that we'll stick to building a RESTful API
> based on the existing web standards surrounding social services.

Your initiative is appreciated (at least by me). Thanks for getting
the ball rolling.



Pistos

[David Kettler]

On Thursday, October 13, 2011 7:47:37 PM UTC-7, Pistos wrote:

On Oct 13, 6:53 pm, David Kettler <21ec...@gmail.com> wrote:
> Alright guys and gals, time for the first real project of this group:
> defining a simple, powerful, secure, open, and extensible API for Diaspora*

Good show!  I've already wanted to do something programmatically with
Diaspora, and was a bit disappointed to see that there wasn't any API
yet.  So this initiative of yours is welcome.

> Now, on to the meaty stuff: where we should start with data types. Luckily,
> there has been a *lot* of work, both from academia and from enterprise,
> around defining Social APIs. The best combination of openness,
> comprehensiveness, and highly-adopted-ness I believe is clearly OpenSocial.

> For People, we'll use Portable Contacts
> For Aspects, we'll use OpenSocial Groups
> For Posts, we'll go with ActivityStreams
> For Comments, we'll also go with ActivityStreams

Can you tell us why we shouldn't just expose the data as a nearly
literal "to_json" translation of the objects?  This seems to me the
approach which would be simplest, most straight-forward, and easiest
to understand and get started with.  Having to deal with a mapping of
DB columns to RFC field names would be added mental taxation, a source
of confusion and a hindrance to learning the system and getting things
done.

When exposing services to the web, one should *always* make sure they comply with any existing open standards. Open standards are the way developers across the web agree on one canonical way to handle a specific data type, like a contact. While you as a D* developer may be fine just learning how D* works and writing clients to interact with it alone, there are people who want to write tools that work with many different social networks, or already have old code lying around/are relying libraries, and for those people it's important to change as little as possible for them. Ideally, they should be able to take any existing code and swap out the domain portion of their request strings and it will Just Work.

In addition to the interoperability gains, you get to rely on all the hard work and QA and thought and testing other (professionals) have already put in. And on top of that, you get a lot more respect from the developer community. D* got a lot of flack among developers I know at the beginning for having what is still viewed as an effectively proprietary communication protocol. We really don't want to have that happen again.

TL;DR: conforming to existing standards keeps existing code working, is less work medium-term, and is the only socially acceptable thing to do.

Now, we may come to some points where the existing standards do not fit our needs. At that point, we iterate with the standards body to see if we can convince them of the important use case, or we fork and make note of exactly why we needed to.
 

> with limited modifications. Mainly, we want to be RESTful on JSON as well as
> XML (in fact, I'd shoot for JSON support before XML support), and I don't

JSON is fine with me, and I could do without any XML, but I don't see
what the big deal about REST is, personally.  Having said that, I
wouldn't resist intent to adhere a little or a lot to REST.

REST is just super simple, and it's by the guy who basically invented HTTP. AFAIK, it beat out RPC and SOAP and the rest as the "right" way to do things. It fits in perfectly with the vision laid out for the web by Tim Berners Lee... read up at http://en.wikipedia.org/wiki/Representational_state_transfer
 

> know if we need the RPC component. We'll mainly want to hear real-dev
> feedback here, as they know their apps better than we do :)

For my particular [first] use case, I merely want to be able to post
new messages and comments [on those messages], and all this to a
single account under my control.

Sadly, I think we're going to write the read portion first, so you may have to wait a bit :)
 

> To be clear, a lot of the wording above sounds dictatorial-- I did not mean
> it as such, it's just way easier to type that way :) The entirety of this
> post is up for debate, but I hope that we'll stick to building a RESTful API
> based on the existing web standards surrounding social services.

Your initiative is appreciated (at least by me).  Thanks for getting
the ball rolling.



Pistos

Thanks for the feedback! Hope I was able to clarify why I made some of those decisions :)

--David

[Ricardo Wurmus]

I agree, it must be RESTful.

So, how's this going to be implemented? Shall we add a special API
controller which handles the requests or simply expose JSON format
(with respond_to / respond_with) on the existing controllers?

What URLs would we like to have?

[Ricardo Wurmus]

PS: rails is RESTful already, so a RESTful API is really the easiest
way to get there.

Adding this to the end of the routes.rb table, we can expose some
interfaces by routing them to the appropriate controller action:

scope "/api/v1" do
scope "/post" do
get ":id" => "status_message#show"
...
end
scope "/user" do
...
end
end

The show action in the status_message controller (I just make this
stuff up) would then have to respond_to JSON or whatever format we
eventually decide on. With something like this we could then fetch
post 12 of the authenticated user:

https://pod.domain.name/api/v1/post/12

Let's make up some resources first that we want to expose and take it
from there.

[Michael Sofaer]

One place that might be worth looking at before you get started coding
APs is the NotificationsController. I rewrote it to support a
transparent JSON API when I was working on the notifications dropdown,
and it seems to be working pretty well. The strategy I used there is
to have the HTML templates consume the API response when building the
page, which I am hoping helps keep the API and web site in sync
feature-wise, if that's a goal.

Cheers and good luck!

-Michael

On Oct 14, 12:27 am, Ricardo Wurmus <ricardo.wur...@gmail.com> wrote:
> PS: rails is RESTful already, so a RESTful API is really the easiest
> way to get there.
>
> Adding this to the end of the routes.rb table, we can expose some
> interfaces by routing them to the appropriate controller action:
>
> scope "/api/v1" do
>   scope "/post" do
>     get ":id" => "status_message#show"
>     ...
>   end
>   scope "/user" do
>     ...
>   end
> end
>
> The show action in the status_message controller (I just make this
> stuff up) would then have to respond_to JSON or whatever format we
> eventually decide on. With something like this we could then fetch
> post 12 of the authenticated user:
>
>    https://pod.domain.name/api/v1/post/12
>
> Let's make up some resources first that we want to expose and take it
> from there.
>

[Dennis Schubert]

For your interest: I am currently working at a document specifying the
basic API methods. I'm in contact with Ilya to define some standards we
wanna use. You can find the WIP at
https://github.com/diaspora/diaspora/wiki/API-v1

Unfortunately I have to go now. I'll continue work in some hours. All my
work should be online this evening (~8h). I'd be happy about every
comment. :)

> --
> Dennis Schubert

[Sarah Mei]

I don't agree that we should always go with standards. There are
significant drawbacks to using someone else's format:

1. Standards are always a compromise and thus more complex than what
any one app needs. This means it will be:
* more overhead for development and testing
* less intuitive to use
As an open source project that lives and dies by its development
community, we need to place a premium on learnability and
approachability of the system code, which closed systems don't need to
worry about. Of course we need to balance that against approachability
of the API itself for outside developers. But it means standards
aren't the obvious choice, like they might be on a closed project.

2. xml - are you fucking kidding me? NO API OF MINE WILL GO OUT
LOOKING LIKE THAT. (kidding! just practicing for when my daughter is a
teenager. but really, all we need is json.)

YAGNI applies even to APIs and standards. :) So to start off, I think
we should look at the standards, but implement the simplest thing that
could possibly work. That's probably a set of standard rails rest
interface methods that return json. We can always put a standards
layer on top of it later, but let's keep the basic API simple and
straightforward.

[elf Pavlik]

Excerpts from Sarah Mei's message of 2011-10-14 16:08:55 +0200:

I would suggest trying to coordinate it with developers of other federated platforms which people use and people using diaspora may like to connect with. At this moment I consider a W3C FSW XG [1] (soon moving to a Community Group) sort of a common ground but we can use any other corner of cyberspace. Do you collaborate with anyone else then Friendika? How about Appleseed or Lorea?

[1] http://federatedsocialweb.net

[Tom Scott]

Response is below...

On Friday, October 14, 2011 at 10:08 AM, Sarah Mei wrote:

1. Standards are always a compromise

Never say never. Or always. ;-) 

2. xml - are you fucking kidding me? NO API OF MINE WILL GO OUT
LOOKING LIKE THAT. (kidding! just practicing for when my daughter is a
teenager. but really, all we need is json.)

I can understand why we shouldn't really give a lot of attention to XML these days, but considering Rails has this shit built-in why don't we just add the response type in each controller for the hell of it?

YAGNI applies even to APIs and standards. :) So to start off, I think
we should look at the standards, but implement the simplest thing that
could possibly work. That's probably a set of standard rails rest
interface methods that return json. We can always put a standards
layer on top of it later, but let's keep the basic API simple and
straightforward.

Agreed wholeheartedly. Constructing a simple JSON API from what Rails already provides us would be the most simple and fastest way of getting the API out there so the devs can start using (and stress testing) it. However, I feel we should design the API to leave room for a "translation layer" that will talk in the language of the open standards, thereby reducing our work later on if these standards are truly adopted by the entire social network development community. 

-T

[Dennis Schubert]

Sarah, I have to agree with you. I was not talking about implementing the whole standards, just the parts we need. Look at the draft I have written down to the wiki. The whole message-stuff is using parts of ActivityStreams and PortableContacts and it's looking fine. :)

[I don't like XML, too.]

--
You received this message because you are subscribed to the Google Groups "diaspora-dev" group.

[Pistos]

On Oct 14, 2:52 am, David Kettler <21ech...@gmail.com> wrote:
> When exposing services to the web, one should *always* make sure they comply
> with any existing open standards. Open standards are the way developers
> across the web agree on one canonical way to handle a specific data type,
> like a contact. While you as a D* developer may be fine just learning how D*
> works and writing clients to interact with it alone, there are people who
> want to write tools that work with many different social networks, or
> already have old code lying around/are relying libraries, and for those
> people it's important to change as little as possible for them. Ideally,
> they should be able to take any existing code and swap out the domain
> portion of their request strings and it will Just Work.

Okay, but who exactly wants to interoperate with Diaspora right
now? :)

if people_who_want_to_interoperate_with_us_right_now.any?
give_ourselves_a_hard_time
else
dont_give_ourselves_a_hard_time
end

> In addition to the interoperability gains, you get to rely on all the hard
> work and QA and thought and testing other (professionals) have already put

This is a good reason.

> in. And on top of that, you get a lot more respect from the developer
> community. D* got a lot of flack among developers I know at the beginning
> for having what is still viewed as an effectively proprietary communication
> protocol. We really don't want to have that happen again.

If nobody wants to do anything with a Diaspora API right now except
Diasporans, then this is not an issue at the moment.

> TL;DR: conforming to existing standards keeps existing code working, is less
> work medium-term, and is the only socially acceptable thing to do.

What existing code? Can you link to any existing projects that (a)
could interoperate with Diaspora and (b) have expressed any interest
in doing so?

> > REST is just super simple, and it's by the guy who basically invented HTTP.
>
> AFAIK, it beat out RPC and SOAP and the rest as the "right" way to do
> things. It fits in perfectly with the vision laid out for the web by Tim
> Berners Lee... read up athttp://en.wikipedia.org/wiki/Representational_state_transfer

I'm not asking Wikipedia to explain to me, I'm asking you. :)

In my opinion, answering the question "Why do you use REST?" with
"somebody else said I should" or "everyone else seems to be doing it"
is just not good enough. :) I'm not saying REST is or is not good or
bad, but if one is merely bandwagonning, one may as well just say "I
believe Jesus will come flying down from the sky one day, because
somebody told me so", or equivalent. Also, Appeal to Authority alone
is insufficient reason (though it does help to convince).

> > Sadly, I think we're going to write the read portion first, so you may have
> to wait a bit :)

I don't see what we have to wait for. Let's do all the core endpoints
up front, and make it as secure as it needs to be for the first
release. Then iterate. (RERO)

If nobody else codes the write endpoint(s) in the first release, I
probably will. :)

> Thanks for the feedback! Hope I was able to clarify why I made some of those
> decisions :)

A little more yet, but we're getting there. :)




Pistos

[David Kettler]

Yup! that's the plan. And yes, editing routes.rb is the way to get the urls we want probably (/api/version_num/resource)

[David Kettler]

Looks good! I'll wait til you're done to do a full compare/contrast with my working doc. One immediate thought: why have /streams and /posts?

On Friday, October 14, 2011 3:35:53 AM UTC-7, Dennis Schubert wrote:

For your interest: I am currently working at a document specifying the
basic API methods. I'm in contact with Ilya to define some standards we
wanna use. You can find the WIP at
https://github.com/diaspora/diaspora/wiki/API-v1

Unfortunately I have to go now. I'll continue work in some hours. All my
work should be online this evening (~8h). I'd be happy about every
comment. :)

Am 14.10.2011 10:29, schrieb Michael Sofaer:
> One place that might be worth looking at before you get started coding
> APs is the NotificationsController.  I rewrote it to support a
> transparent JSON API when I was working on the notifications dropdown,
> and it seems to be working pretty well.  The strategy I used there is
> to have the HTML templates consume the API response when building the
> page, which I am hoping helps keep the API and web site in sync
> feature-wise, if that's a goal.
>
> Cheers and good luck!
>
> -Michael
>

[David Kettler]

On Friday, October 14, 2011 7:08:55 AM UTC-7, Sarah Mei wrote:

I don't agree that we should always go with standards. There are
significant drawbacks to using someone else's format:

1. Standards are always a compromise and thus more complex than what
any one app needs. This means it will be:
  * more overhead for development and testing
  * less intuitive to use
As an open source project that lives and dies by its development
community, we need to place a premium on learnability and
approachability of the system code, which closed systems don't need to
worry about. Of course we need to balance that against approachability
of the API itself for outside developers. But it means standards
aren't the obvious choice, like they might be on a closed project.

I agree that we should value learnability and approachability over standards, but let's think about what the value of learnability and approachability really are: getting a wealth of other clients which can interoperate with Diaspora as friction-free as possible. By ignoring standards, we kick out two huge classes of people: people who have already written social applications and utilities (our main dev base for the API, IMO), and people who look down on people who don't use standards (the majority of the FOSS and web community). We can have the easiest, most dead-simple API that anyone's ever seen, but if I have to relearn it rather than relying on the standards I already know, rewrite all my code to work with it, and know I'll never be able to use this code for anything other than D*… I'm very unlikely to take that effort.

This is what I was trying to go for with my comments about "limited modifications" to the OpenSocial spec (which it looks like my hastily-rewritten-because-gmail-decided-to-go-take-a-shit-or-something didn't expand enough on, so i'll do so here): I haven't been over the OpenSocial server spec with a fine-tooth comb (which I should before we go much further), but my few skims have led me to believe that there are a few (but only a few!) little stupid, non-intuitive things. Those we should iron out. But the point is that we should be able to say with a straight face to the public "our API is standards compliant".

 

2. xml - are you fucking kidding me? NO API OF MINE WILL GO OUT
LOOKING LIKE THAT. (kidding! just practicing for when my daughter is a
teenager. but really, all we need is json.)

Precisely. Although as Tom Scott says, we should eventually do it because it's really not too hard with Rails.
 

YAGNI applies even to APIs and standards. :) So to start off, I think
we should look at the standards, but implement the simplest thing that
could possibly work. That's probably a set of standard rails rest
interface methods that return json. We can always put a standards
layer on top of it later, but let's keep the basic API simple and
straightforward.

Exactly-- as I said, we'll be starting with a limited number of resources (people, aspects, posts, comments), implementing them in accordance with a standard, and then iterating out from there. And, as you say, that means "standard rails rest interface methods that return json"-- that's all the OpenSocial spec is :)

[David Kettler]

Looking over that web site, basically every one of them uses PoCo and ActivityStreams :)

[David Kettler]

As I said to Sarah above, a simple restful json api *is* what the standards are. As far as "getting something out there ASAP", I completely agree, but have a couple of caveats. When you make an API, it is *extremely* hard to change it. Every change means asking your developers to rewrite their code. Too many and too drastic changes mean you lose all your developers. This is why I think we should iterate on the scope of release of the API on top of iterating on what methods are provided-- so we don't get people relying on an API before it's ready.

[Dennis Schubert]

Because /stream/1 makes is bad and /posts is somehow bad, too. In my
opinion it's not clear that you'll get a stream if you request /posts.

At the moment I'm enabling devise's http basic auth - I'll push it to
the branch "api" in a minute.

--

You received this message because you are subscribed to the Google Groups "diaspora-dev" group.

To view this discussion on the web visit https://groups.google.com/d/msg/diaspora-dev/-/G7YPql3auCgJ.

[David Kettler]

On Friday, October 14, 2011 9:03:22 AM UTC-7, Pistos wrote:

On Oct 14, 2:52 am, David Kettler <21ec...@gmail.com> wrote:
> When exposing services to the web, one should *always* make sure they comply
> with any existing open standards. Open standards are the way developers
> across the web agree on one canonical way to handle a specific data type,
> like a contact. While you as a D* developer may be fine just learning how D*
> works and writing clients to interact with it alone, there are people who
> want to write tools that work with many different social networks, or
> already have old code lying around/are relying libraries, and for those
> people it's important to change as little as possible for them. Ideally,
> they should be able to take any existing code and swap out the domain
> portion of their request strings and it will Just Work.

Okay, but who exactly wants to interoperate with Diaspora right
now?  :)

if people_who_want_to_interoperate_with_us_right_now.any?
  give_ourselves_a_hard_time
else
  dont_give_ourselves_a_hard_time
end

Again, I think we all need to rethink how much of a "hard time" standards are. Literally the *only* additional work beyond implementing these in the standard Rails/RESTful way is making sure that our fields are named and nested correctly, which should be pretty trivial.
 

> In addition to the interoperability gains, you get to rely on all the hard
> work and QA and thought and testing other (professionals) have already put

This is a good reason.

> in. And on top of that, you get a lot more respect from the developer
> community. D* got a lot of flack among developers I know at the beginning
> for having what is still viewed as an effectively proprietary communication
> protocol. We really don't want to have that happen again.

If nobody wants to do anything with a Diaspora API right now except
Diasporans, then this is not an issue at the moment.

My argument is that no-one wants anything to do with Diaspora messaging interoperability right now *because* it was not standards compliant. You don't attract devs by telling them everything they've ever done is wrong and you have it right and everyone should pay attention to you. You attract them by telling them how good of a web citizen you are using the web standards, and how working with your site is drop dead easy because of it.

 

> TL;DR: conforming to existing standards keeps existing code working, is less
> work medium-term, and is the only socially acceptable thing to do.

What existing code?  Can you link to any existing projects that (a)
could interoperate with Diaspora and (b) have expressed any interest
in doing so?

 http://activitystrea.ms/ has a list of participants at the bottom.

as far as poco, there's plenty of gems and django apps around. Mozilla's contacts managers use PoCo. All google services uses PoCo.

any developer on the web right now who has written a social application has used activity streams and portable contacts.
 

> > REST is just super simple, and it's by the guy who basically invented HTTP.
>
> AFAIK, it beat out RPC and SOAP and the rest as the "right" way to do
> things. It fits in perfectly with the vision laid out for the web by Tim
> Berners Lee... read up athttp://en.wikipedia.org/wiki/Representational_state_transfer

I'm not asking Wikipedia to explain to me, I'm asking you.  :)

In my opinion, answering the question "Why do you use REST?" with
"somebody else said I should" or "everyone else seems to be doing it"
is just not good enough.  :)  I'm not saying REST is or is not good or
bad, but if one is merely bandwagonning, one may as well just say "I
believe Jesus will come flying down from the sky one day, because
somebody told me so", or equivalent.  Also, Appeal to Authority alone
is insufficient reason (though it does help to convince).

Sorry, I didn't want to appeal to authority, I just wanted to cite authority (and didn't want to rewrite Roy Fielding's paper :)) The wiki page really does a good job summarizing what I'm about to say, but here goes: The web was built as an exchange of formatted data between stateless clients and servers. The Web itself is REST ("The largest implementation of a system conforming to the REST architectural style is the World Wide Web."). REST, or representational state transfer, allows for stateless clients to overcome their statelessness through their discussions with servers. It separates the concerns of the client and the server. It's cacheable. It's general, scalable, and modular. It's dead simple. HTTP and REST were made for each other. Etc.
 

> > Sadly, I think we're going to write the read portion first, so you may have
> to wait a bit :)

I don't see what we have to wait for.  Let's do all the core endpoints
up front, and make it as secure as it needs to be for the first
release.  Then iterate.  (RERO)

If nobody else codes the write endpoint(s) in the first release, I
probably will.  :)

> Thanks for the feedback! Hope I was able to clarify why I made some of those
> decisions :)

A little more yet, but we're getting there.  :)




Pistos

Writing the auth code for modification of the server is almost certainly going to be more complex than writing the code for reading from the server. Writing the read portion first is just to iterate on the smallest scale possible-- exactly as you say: RERO. As I said above in responses to others, with APIs you don't want to have to rewrite them at all once developers are starting to write code using them. As such, we should make sure we are always comfortable with our releases before they go live. The easiest way to achieve that comfort level, IMO, is to scale down our releases to be as small as possible, so we can focus on one thing at a time. Thus, starting with read-only. I don't want to have to have a discussion in this group about the quality of our writing API alongside discussing the quality of our reading API-- that's just going to be overload and delay both releases. I really think we should stick to RERO by releasing iteratively.

Not to be a pessimist-- I'm sure once we've settled on a read-only API, the writing API will fall right out with minimal effort.

This is the change I'm most open to, though. Perhaps the best way to have phrased my original statement would have been "if it comes down to deciding between posting/deploying something about the reading API and waiting for the writing API to be ready, I vote we always side with posting/deploying"

[Pistos]

On Oct 14, 1:52 pm, David Kettler <21ech...@gmail.com> wrote:
> My argument is that no-one wants anything to do with Diaspora messaging
> interoperability right now *because* it was not standards compliant. You
> don't attract devs by telling them everything they've ever done is wrong and
> you have it right and everyone should pay attention to you. You attract them
> by telling them how good of a web citizen you are using the web standards,
> and how working with your site is drop dead easy because of it.
>

>  http://activitystrea.ms/has a list of participants at the bottom.

>
> as far as poco, there's plenty of gems and django apps around. Mozilla's
> contacts managers use PoCo. All google services uses PoCo.
>
> any developer on the web right now who has written a social application has
> used activity streams and portable contacts.

If AS and PoCo are so great, then I would like to see a push to
refactor Diaspora's models to conform as closely as possible to AS and
PoCo. Do that first, and then do the API.

> Sorry, I didn't want to appeal to authority, I just wanted to cite authority
> (and didn't want to rewrite Roy Fielding's paper :)) The wiki page really
> does a good job summarizing what I'm about to say, but here goes: The web
> was built as an exchange of formatted data between stateless clients and
> servers. The Web itself is REST ("The largest implementation of a system
> conforming to the REST architectural style is the World Wide Web."). REST,
> or representational state transfer, allows for stateless clients to overcome
> their statelessness through their discussions with servers. It separates the
> concerns of the client and the server. It's cacheable. It's general,
> scalable, and modular. It's dead simple. HTTP and REST were made for each
> other. Etc.

All of this may be true, but it does not convince me that REST
conformance is superior to, say, using GET for read and POST for all
writes. Or using GET for everything. Anyway, I was just getting on
this REST topic for the sake of argument, but let's agree to disagree
so that this API thread doesn't get hijacked or diluted. :) I'll
just say that I still think REST's "rules" are arbitrary.

> Writing the auth code for modification of the server is almost certainly
> going to be more complex than writing the code for reading from the server.

> This is the change I'm most open to, though. Perhaps the best way to have
> phrased my original statement would have been "if it comes down to deciding
> between posting/deploying something about the reading API and waiting for
> the writing API to be ready, I vote we always side with posting/deploying"

I'm still not seeing why the write endpoints can't be done
concurrently with the read. I think the API can be considered a
cohesive whole; it doesn't have to be split in half. Anyway, I can
concede on this point. :)



Pistos

[David Kettler]

On Fri, Oct 14, 2011 at 12:33 PM, Pistos <dev.diasp...@purepistos.net> wrote:

On Oct 14, 1:52 pm, David Kettler <21ech...@gmail.com> wrote:
> My argument is that no-one wants anything to do with Diaspora messaging
> interoperability right now *because* it was not standards compliant. You
> don't attract devs by telling them everything they've ever done is wrong and
> you have it right and everyone should pay attention to you. You attract them
> by telling them how good of a web citizen you are using the web standards,
> and how working with your site is drop dead easy because of it.
>

>  http://activitystrea.ms/has a list of participants at the bottom.

>
> as far as poco, there's plenty of gems and django apps around. Mozilla's
> contacts managers use PoCo. All google services uses PoCo.
>
> any developer on the web right now who has written a social application has
> used activity streams and portable contacts.

If AS and PoCo are so great, then I would like to see a push to
refactor Diaspora's models to conform as closely as possible to AS and
PoCo.  Do that first, and then do the API.

They're already pretty close... I'll compile a list of the precise differences shortly and post them here, then we can consider whether or not we should migrate all the tables (that seems like a pretty expensive operation, though)
 

> Sorry, I didn't want to appeal to authority, I just wanted to cite authority
> (and didn't want to rewrite Roy Fielding's paper :)) The wiki page really
> does a good job summarizing what I'm about to say, but here goes: The web
> was built as an exchange of formatted data between stateless clients and
> servers. The Web itself is REST ("The largest implementation of a system
> conforming to the REST architectural style is the World Wide Web."). REST,
> or representational state transfer, allows for stateless clients to overcome
> their statelessness through their discussions with servers. It separates the
> concerns of the client and the server. It's cacheable. It's general,
> scalable, and modular. It's dead simple. HTTP and REST were made for each
> other. Etc.

All of this may be true, but it does not convince me that REST
conformance is superior to, say, using GET for read and POST for all
writes.  Or using GET for everything.  Anyway, I was just getting on
this REST topic for the sake of argument, but let's agree to disagree
so that this API thread doesn't get hijacked or diluted.  :)  I'll
just say that I still think REST's "rules" are arbitrary.

GET for read and POST for writes == REST (well, plus DELETE for deleting)
 

> Writing the auth code for modification of the server is almost certainly
> going to be more complex than writing the code for reading from the server.

> This is the change I'm most open to, though. Perhaps the best way to have
> phrased my original statement would have been "if it comes down to deciding
> between posting/deploying something about the reading API and waiting for
> the writing API to be ready, I vote we always side with posting/deploying"

I'm still not seeing why the write endpoints can't be done
concurrently with the read.  I think the API can be considered a
cohesive whole; it doesn't have to be split in half.  Anyway, I can
concede on this point.  :)

They can be, it's just more work. If we have enough people on the project, then it shouldn't be too much of a concern. I just want to be sure we use our limited resources in efficient and productive a way as possible.

--David

[Sarah Mei]

So, a couple of things -

>> On Oct 14, 1:52 pm, David Kettler <21ech...@gmail.com> wrote:
>> > My argument is that no-one wants anything to do with Diaspora messaging
>> > interoperability right now *because* it was not standards compliant.

The only people who care about whether we're standards compliant are
other distributed social networks, large companies, and big OSS
projects. That's not who we need to target right now. *Right now* we
need to target people who are already on Diaspora, love it, and want
to build simple extensions in the form of applications. For those
people, a drop-dead simple json API that looks like our existing
object model is the easiest thing.

>> > You
>> > don't attract devs by telling them everything they've ever done is wrong
>> > and you have it right and everyone should pay attention to you. You attract
>> > them by telling them how good of a web citizen you are using the web
>> > standards, and how working with your site is drop dead easy because of it.

This applies to a breed of OSS developer that we are not currently
targeting - folks who work on apache projects, mozilla, other DSNs,
whatever. We, on the other hand, need to attract the scrappy
independents. When we get bigger, we should totally build what the
apache folks need. But first we need to get bigger.

So how do we do that? By enabling passionate individual developers who
will build awesome apps. And for them the ideal API is much different
- it should look like what we have already.

I'm sure you all read Steve Yegge's rant about platforms (if not, go
do that now -
https://plus.google.com/112678702228711889851/posts/eVeouesvaVX
).

His main point is that Amazon and Facebook are successful because they
think in terms of a platform (i.e. APIs, standards, etc.). He then
argues that Google (where he currently works) should focus at the
corporate level on thinking in terms of platform rather than products.

He's right - a company of Google's size should certainly be trying to
become a platform. One thing he sorta skims over, though, is the
relationship between products and platforms. There are 2 things to
think about here:

1. How Facebook became a platform.

First, they built a product people loved. Only after they had that did
they focus on building a platform.

2. Why other distributed social networks haven't taken off.

There have been many, many other DSN projects. None of them have
gotten the traction that Diaspora has gotten. One of the major reasons
for that is that they focused first on building a protocol and an API.
They thought a good platform would attract developers, which would
grow the userbase.

They all put the cart before the horse - you need a *product* people
love to use first. Then, and only then, will you get the opportunity
to create a platform out of it.

Diaspora isn't at that point yet. We can get there, though, partially
by enabling these passionate independent developers to build cool
stuff into an already-cool product. So the API we build needs to be
tailor-made for that audience. I don't think we should do any extra
work to conform to standards. If our stuff happens to line up with an
existing standard, great. Bonus! But our first priority should be ease
of use and understandability, and we should not compromise on that
even if it means not conforming to a standard.

> [The current models] already pretty close [to the standards]... I'll compile a list of the precise

> differences shortly and post them here, then we can consider whether or not
> we should migrate all the tables (that seems like a pretty expensive
> operation, though)

I have no problem making database changes if it's the right thing to
do for code clarity. There are lots of things with unclear names in
our current codebase, so it might be a good idea to look to the
standards for naming ideas.

As for REST, we should do it because the rest of the app does it,
because Rails does it, and because it's easy.

As for XML - YAGNI. No one's asking for it, and if we add it to the
code, we have to test and maintain it. Believe me, it's never as
simple as just turning on the content format. Well, maybe it is if
you're following the build-a-blog-in-5-minutes tutorial, but any
real-world app is way too complex for that. :)

As to whether we should put them in the same controllers, routes, etc.
- separate them. Usage patterns of an API are much different than a
web app, and they'll need to scale differently.

Practically speaking, in most of my projects with APIs, it has worked
best to put them in a version namespace, like
app/controllers/v0/posts_controller.rb, with routes that include the
version numbers. Diaspora may end up releasing many versions of our
API, which could be super annoying, but...we'll cross that bridge when
we're lucky enough to come to it.

Finally, I am very grateful to David for starting this conversation,
even if I don't agree with him that standards are important at this
stage. I really really really hope we get to the stage where they
*are* important. :)

Sarah

[Michael Sofaer]

I think that Yegge's point about dogfooding it and doing things in
"the right way" that he talks about Amazon working is in opposition to
separating web routes from API routes. As long as the routes are
separate, developers can build web features that can't be duplicated
in the API, and the API is relegated to second-class status. Yegge is
arguing for making the API a first-class citizen, and the product
dependent on it. Or at least, that's my take, and given my
prejudices, possibly it's all in my head.

-Michael

On Oct 14, 2:07 pm, Sarah Mei <sa...@joindiaspora.com> wrote:

> I'm sure you all read Steve Yegge's rant about platforms (if not, go

> do that now -https://plus.google.com/112678702228711889851/posts/eVeouesvaVX

> ).
>
> His main point is that Amazon and Facebook are successful because they
> think in terms of a platform (i.e. APIs, standards, etc.). He then
> argues that Google (where he currently works) should focus at the
> corporate level on thinking in terms of platform rather than products.

...

[Sarah Mei]

On Fri, Oct 14, 2011 at 2:25 PM, Michael Sofaer <goo...@mike.sofaer.net> wrote:
> I think that Yegge's point about dogfooding it and doing things in
> "the right way" that he talks about Amazon working is in opposition to
> separating web routes from API routes.  As long as the routes are
> separate, developers can build web features that can't be duplicated
> in the API, and the API is relegated to second-class status.  Yegge is
> arguing for making the API a first-class citizen, and the product
> dependent on it.  Or at least, that's my take, and given my
> prejudices, possibly it's all in my head.

I totally agree. Companies that already have a product with
(m|b)illions of users have this luxury, and they should take it.

Startups, OTOH, need to optimize for quick iterations and
responsiveness to a changing business climate. They need that
flexibility so they can make a product people love. Once they have
that, then they can worry about the platform transition.

Twitter built the app first, then the API, then rewrote the main app
to use the API. That gave them the flexibility at the beginning when
they really needed it, but now the platform is really the product.
It's a great example for us of a successful product -> platform
transition.

[Tom Scott]

It's also a great example of an entire platform built off of something quite simple. The Twitter API is still just as easy to work with as it was when it began, yet it's increased its complexity. 

-T

--
You received this message because you are subscribed to the Google Groups "diaspora-dev" group.

[Jarkko Moilanen]

> protocol. We really don't want to have that happen again.

If nobody wants to do anything with a Diaspora API right now except
Diasporans, then this is not an issue at the moment.

Some app developers that I know would like to have easy-to-use (preferably restful) API they could use in mobile/handheld app development (Qt based, not that it has any matter). 

/Jarkko

 

Pistos

[David Kettler]

Alright, I think we can compromise on the following: we'll start by just making the models we want to be accessible via API have a format.json (or format.api or something if we want to separate the API from where we already use format.json) which just throws all the (accessible) values in the table into a json object.

Moving forward, we'll namespace an api like /api/poco/v0/ or api/activitystreams/v0/ or whatever, and requests to those URLs will return standards-based json values. This way also allows for us to have something like /api/facebook/v0/ or something else if people want to write schema translation scripts for communication with other sites. This will be a little fragmenting, but we'll probably decide to only let ones with a large enough/legitimate use case onto the server.

Also, as we write these standards-translator scripts, it may prompt us to revise the diaspora schema for values we may actually want to start storing (for instance, diaspora right now can't handle middle names, honorifics (Mr., Jr., etc.), and some others).

As I hope I expressed earlier, my main motivation for starting off the bat with standards-compliant APIs was so that no dev had to rewrite their apps when we moved to standards-- by not starting with standards-based APIs, we're guaranteeing ourselves at least one major API rewrite. But if we namespace them separately (and maintain both/slowly deprecate one), then that shouldn't be an issue. Having a diaspora-specific API will also allow us to innovate on the API itself, fields we wanna pass around that other services don't really care about, etc.

Does that sound good?

--dK

[Jason Lewis]

How, exactly, is this preferable to following existing Rails paradigms and adding a respond_to :json clause to controller actions?

Maybe it's just me, but this APP implementation proposal seems like a maintenance nightmare down the road.

On Oct 13, 2011 6:53 PM, "David Kettler" <21ec...@gmail.com> wrote:

So I just posted this to the diaspora-services group, but I know not all people interested in APIs are over there, so I've cross-posted it here.

---

Alright guys and gals, time for the first real project of this group: defining a simple, powerful, secure, open, and extensible API for Diaspora*

To keep this process moving and scale it reasonably, we'll use the following release cycle:
    1.    Discuss
    2.    Post mock version of the API for public feedback
    3.    Deploy read-only version of the API for consumption by a private alpha pool of developers
    4.    Open up the read-only API to anyone, deploy a writable version of the API to a private alpha pool of developers
    5.    Fully open the reading and writing API

We will start this process on the main 4 diaspora resources: People, Aspects, Posts, and Comments. As we wish to make other resources available, we will submit them to the same release process to ensure quality and scalability.

Now, on to the meaty stuff: where we should start with data types. Luckily, there has been a *lot* of work, both from academia and from enterprise, around defining Social APIs. The best combination of openness, comprehensiveness, and highly-adopted-ness I believe is clearly OpenSocial. As such, we should shoot for their API server spec: http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-API-Server.xml with limited modifications. Mainly, we want to be RESTful on JSON as well as XML (in fact, I'd shoot for JSON support before XML support), and I don't know if we need the RPC component. We'll mainly want to hear real-dev feedback here, as they know their apps better than we do :)

To clarify, RESTful means
to read a list, GET /plural_resource
to read an item, GET /plural_resource/id
to create an item, POST /plural_resource
to update (by replacement) a list, PUT /plural_resource
to update (by replacement) an item, PUT /plural_resource/id
to delete a list, DELETE /plural_resource
to delete an item, DELETE /plural_resource/id

the PUT/POST mapping to create/update/replace is often murky (basically, a lot of servers ignore PUT and ask that all creating/updating be done through POST)-- some input here on how by-the-books RESTful we want to be would be nice :) (check out http://stackoverflow.com/questions/630453/put-vs-post-in-rest for some discussion).

For People, we'll use Portable Contacts http://portablecontacts.net/draft-spec.html (which OpenSocial is aligned with)

For Aspects, we'll use OpenSocial Groups http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-Data.xml#Group (this may need some small modification to make them as rich as D* aspects… namely, whether or not the specified group is publicly listed or not)

For Posts, we'll go with ActivityStreams: http://activitystrea.ms/specs/json/1.0/ which has a schema defined at http://activitystrea.ms/head/activity-schema.html

For Comments, we'll also go with ActivityStreams (see http://activitystrea.ms/head/activity-schema.html#comment)

To be clear, a lot of the wording above sounds dictatorial-- I did not mean it as such, it's just way easier to type that way :) The entirety of this post is up for debate, but I hope that we'll stick to building a RESTful API based on the existing web standards surrounding social services.

Thanks,
David

--
You received this message because you are subscribed to the Google Groups "diaspora-dev" group.

To view this discussion on the web visit https://groups.google.com/d/msg/diaspora-dev/-/uhTxnB5zRhIJ.

[Jason Lewis]

Here's the thing with standards, learnability, etc.: developers don't give a shit. We yeah a library. I want Twitter in my Ruby app? I grab the Twitter gem. So D* could have the most retarded, stupid, standards-fucking API ever, and if there is a solid lib I can add to my Gemfile, nobody cares. That's all I'm saying.

--

You received this message because you are subscribed to the Google Groups "diaspora-dev" group.

To view this discussion on the web visit https://groups.google.com/d/msg/diaspora-dev/-/_WtSJIzcZdgJ.

[Ricardo Wurmus]

There is not a big difference. I believe all he is suggesting is to
namespace the API by means of routes.

It's still the Rails way, but with an added layer of abstraction to be
able to transparently change the dispached methods without necessarily
affecting the public interface.

Also, encapsulating calls through routes makes it possible to
effectively version the API.

> > http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-API-Server.xmlwith limited modifications. Mainly, we want to be RESTful on JSON as well as

> > XML (in fact, I'd shoot for JSON support before XML support), and I don't
> > know if we need the RPC component. We'll mainly want to hear real-dev
> > feedback here, as they know their apps better than we do :)
> >
> > To clarify, RESTful means
> > to read a list, GET /plural_resource
> > to read an item, GET /plural_resource/id
> > to create an item, POST /plural_resource
> > to update (by replacement) a list, PUT /plural_resource
> > to update (by replacement) an item, PUT /plural_resource/id
> > to delete a list, DELETE /plural_resource
> > to delete an item, DELETE /plural_resource/id
> >
> > the PUT/POST mapping to create/update/replace is often murky (basically, a
> > lot of servers ignore PUT and ask that all creating/updating be done through
> > POST)-- some input here on how by-the-books RESTful we want to be would be
> > nice :) (check out
> > http://stackoverflow.com/questions/630453/put-vs-post-in-rest for some
> > discussion).
> >
> > For People, we'll use Portable Contacts
> > http://portablecontacts.net/draft-spec.html (which OpenSocial is aligned
> > with)
> >
> > For Aspects, we'll use OpenSocial Groups

> > http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-Data.xml#Group(this may need some small modification to make them as rich as D* aspects…

[Sarah Mei]

On Sat, Oct 15, 2011 at 4:37 PM, David Kettler
<david.b...@gmail.com> wrote:
> Also, as we write these standards-translator scripts, it may prompt us to
> revise the diaspora schema for values we may actually want to start storing
> (for instance, diaspora right now can't handle middle names, honorifics
> (Mr., Jr., etc.), and some others).

So here we run into some philosophical differences between Diaspora -
me specifically - and the folks who write standards.

For the most part, we don't store that extra information because it's
not really useful to us. It's super useful if you're doing data
mining, but Diaspora explicitly does not. Most of the companies who
participate in the standards process depend on data mining to make
their quarterly numbers, so it's easy to see where the disconnect
arises.

Diaspora also has a textfield for gender, which was a deliberate
recognition of the multiplicity of gender, and also an explicit
acknowledgement that data mining is not one of our goals. AFAICT that
won't fit with any current standard that specifies gender.

These aren't unbridgeable divides, but they do suggest that a purely
standards-based API would mask many of the things that make Diaspora
awesome.

> As I hope I expressed earlier, my main motivation for starting off the bat
> with standards-compliant APIs was so that no dev had to rewrite their apps
> when we moved to standards-- by not starting with standards-based APIs,
> we're guaranteeing ourselves at least one major API rewrite.

Actually no. I don't think we should ever deprecate the Diaspora-style
API. Instead, we should use it as a base to implement the
standards-compliant ones. We will need both, because they're built for
different audiences. They will probably have different capabilities
given the philosophical differences between us and the folks who write
social data standards.

Once we have the basic Diaspora API, we'll be able to write
independent translation classes that transform a standard into our
format, and then pass it to the relevant Diaspora-style API call. That
way we get what we need now - something simple for folks to start
playing with, and something that truly reflects the richness of our
community - and we also get a set of building blocks we can use to
implement standards down the road.

[Mike Dupont]

Has there been any code released about the api? what branches/forks
should I be following?
thanks,
mike

--
James Michael DuPont
Member of Free Libre Open Source Software Kosova http://flossk.org

[Sarah Mei]

We're working in master. Right now there are only 2 methods available - get a public profile given a username, and get tag metadata (not even posts yet) given a tag name. It's not ready for official use - it's more of an example for developers to look at and give feedback on.

Speaking of which, we'd like to get feedback on the pattern - we split out json serializer classes from the models. Max or I will send out a more detailed request for feedback later today.

> James Michael DuPont
> Member of Free Libre Open Source Software Kosova http://flossk.org
>

> --
> You received this message because you are subscribed to the Google Groups "diaspora-dev" group.

[Mike Dupont]

thanks,
I am working on testing code, removing the rails and database code. I
have Profile, Person and Webfinger now running somehow on the command
line.
I am learning about the ostatus api, basically from what I understand
I should be able to register a pod and sign messages with solomon to
talk to users. Other than that is there a push api for webfinger? or
is it pull? I would like to be able to push status updates from my
command line pod to the server, if that makes sense?
mike

[Maxwell Salzberg]

Hey everyone,

Sorry I have been silent on this thusfar.  I really appreciate all of your enthusiasm for having us make an awesome API.

I want to throw my weight behind Sarah's reasoning.

My concern right now is less what data our endpoints produce(whether it is valid ActivityStreams, Dublin core, socialjibjabwhatever), but that it is really easy to make out API output whatever format of data you like.

Sarah and I had some facetime on it this weekend, and we both agreed that if we want to achieve this, we needed to see what making a bunch of little serializer classes looked like, and then do a decent refactor to try and make it a bit more magical and easier for community members to fill out the enumeration of the endpoints of the API.

So right now, we don't have the pattern we want exactly of how we are going to write it.  We want it to be flexible and give us the data we would want from an API(so not just a serialization of database rows, but actual things that people can use) and then work on building little translators into useful data formats that people want to consume.

Tags and Public profile data are just the first example.  They need to be fleshed out a bunch more.  My plan is to try to sprint to make these two endpoints as complete as possible, that way it will be really simple for a contributor to look at the pattern, and fill out conversations/postings, kind of like how David ran with our "stream" object and added a huge feature (Notes) with ease.

With that being said, if we could try to optimize for community involvement in building and extending the API, rather than focusing on what-route-should-go-where, I bet we can make something OSSIM.

xoxox

maxwell

[Mase]

Very cool. I've been lurking for a while now. It takes a discussion on
API design to draw me out. :)

> the PUT/POST mapping to create/update/replace is often murky (basically, a lot of servers ignore PUT and ask that all creating/updating be done through POST)-- some input here on how by-the-books RESTful we want to be would be nice

The larger problem tends to be clients (e.g., browsers) which
sometimes only speak GET/POST, resulting in the need to use POST but
treat it like DELETE/PUT, often using an additional header or
parameter to tell the server of the client's intention. Only recently
have browsers widely begun giving we devs a way of specifying
alternative verbs. Most mainstream browsers allow PUT/DELETE via XHR,
but PUT/DELETE via HTML forms was dropped from the HTML5 spec last I
heard.
The server, however, is often yours, and you can do whatever you like
to support arbitrary verbs. In fact, REST isn't limited to GET/PUT/
POST/DELETE - the stipulation of the architecture (it's not a
protocol) is only that you use HTTP methods, of which there are nine,
some of which aren't always useful for representational state transfer
(I don't know when you'd ever want to issue/accept a PATCH, for
instance, as applying partial updates is hard at scale).
It would be worth keeping OPTIONS in mind, as that's what CORS uses to
determine if cross-domain communication is allowed in modern browsers.
Under what conditions do you allow it? How does that impact
authentication, or vice versa, etc.

On Oct 13, 2:53 pm, David Kettler <21ech...@gmail.com> wrote:
> So I just posted this to the diaspora-services group, but I know not all
> people interested in APIs are over there, so I've cross-posted it here.
>
> ---
> Alright guys and gals, time for the first real project of this group:
> defining a simple, powerful, secure, open, and extensible API for Diaspora*
>
> To keep this process moving and scale it reasonably, we'll use the following
> release cycle:
>     1.    Discuss
>     2.    Post mock version of the API for public feedback
>     3.    Deploy read-only version of the API for consumption by a private
> alpha pool of developers
>     4.    Open up the read-only API to anyone, deploy a writable version of
> the API to a private alpha pool of developers
>     5.    Fully open the reading and writing API
>
> We will start this process on the main 4 diaspora resources: People,
> Aspects, Posts, and Comments. As we wish to make other resources available,
> we will submit them to the same release process to ensure quality and
> scalability.
>
> Now, on to the meaty stuff: where we should start with data types. Luckily,
> there has been a *lot* of work, both from academia and from enterprise,
> around defining Social APIs. The best combination of openness,
> comprehensiveness, and highly-adopted-ness I believe is clearly OpenSocial.

> As such, we should shoot for their API server spec:http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-API-Se...

> with limited modifications. Mainly, we want to be RESTful on JSON as well as
> XML (in fact, I'd shoot for JSON support before XML support), and I don't
> know if we need the RPC component. We'll mainly want to hear real-dev
> feedback here, as they know their apps better than we do :)
>
> To clarify, RESTful means
> to read a list, GET /plural_resource
> to read an item, GET /plural_resource/id
> to create an item, POST /plural_resource
> to update (by replacement) a list, PUT /plural_resource
> to update (by replacement) an item, PUT /plural_resource/id
> to delete a list, DELETE /plural_resource
> to delete an item, DELETE /plural_resource/id
>
> the PUT/POST mapping to create/update/replace is often murky (basically, a
> lot of servers ignore PUT and ask that all creating/updating be done through
> POST)-- some input here on how by-the-books RESTful we want to be would be

> nice :) (check outhttp://stackoverflow.com/questions/630453/put-vs-post-in-restfor some
> discussion).
>
> For People, we'll use Portable Contactshttp://portablecontacts.net/draft-spec.html(which OpenSocial is aligned
> with)
>
> For Aspects, we'll use OpenSocial Groupshttp://opensocial-resources.googlecode.com/svn/spec/2.0/Social-Data.x...

> (this may need some small modification to make them as rich as D* aspects…
> namely, whether or not the specified group is publicly listed or not)
>

> For Posts, we'll go with ActivityStreams:http://activitystrea.ms/specs/json/1.0/which has a schema defined athttp://activitystrea.ms/head/activity-schema.html
>
> For Comments, we'll also go with ActivityStreams (seehttp://activitystrea.ms/head/activity-schema.html#comment)

[Mike Dupont]

I have a question, how are the private aspect feeds information
transfered? via public key encryption?
thanks
mike

[voidcode]

Hey.

I have now for some time had the idea to create a Diaspora conversations/sms app for android.

I think that it should act as Facebook Messenger app (https://market.android.com/details?id=com.facebook.orca&hl=da)

But just wire the diaspora as a messenger server.

In this way the diaspora users have the opportunity to "sms" to each other.

I would therefore ask what is the status of api?

And if the API will also support the POST / conversations action?

Den fredag den 14. oktober 2011 00.53.47 UTC+2 skrev David Kettler:

So I just posted this to the diaspora-services group, but I know not all people interested in APIs are over there, so I've cross-posted it here.

---
Alright guys and gals, time for the first real project of this group: defining a simple, powerful, secure, open, and extensible API for Diaspora*

To keep this process moving and scale it reasonably, we'll use the following release cycle:
    1.    Discuss
    2.    Post mock version of the API for public feedback
    3.    Deploy read-only version of the API for consumption by a private alpha pool of developers
    4.    Open up the read-only API to anyone, deploy a writable version of the API to a private alpha pool of developers
    5.    Fully open the reading and writing API

We will start this process on the main 4 diaspora resources: People, Aspects, Posts, and Comments. As we wish to make other resources available, we will submit them to the same release process to ensure quality and scalability.

Now, on to the meaty stuff: where we should start with data types. Luckily, there has been a *lot* of work, both from academia and from enterprise, around defining Social APIs. The best combination of openness, comprehensiveness, and highly-adopted-ness I believe is clearly OpenSocial. As such, we should shoot for their API server spec: http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-API-Server.xml with limited modifications. Mainly, we want to be RESTful on JSON as well as XML (in fact, I'd shoot for JSON support before XML support), and I don't know if we need the RPC component. We'll mainly want to hear real-dev feedback here, as they know their apps better than we do :)

To clarify, RESTful means
to read a list, GET /plural_resource
to read an item, GET /plural_resource/id
to create an item, POST /plural_resource
to update (by replacement) a list, PUT /plural_resource
to update (by replacement) an item, PUT /plural_resource/id
to delete a list, DELETE /plural_resource
to delete an item, DELETE /plural_resource/id

the PUT/POST mapping to create/update/replace is often murky (basically, a lot of servers ignore PUT and ask that all creating/updating be done through POST)-- some input here on how by-the-books RESTful we want to be would be nice :) (check out http://stackoverflow.com/questions/630453/put-vs-post-in-rest for some discussion).

For People, we'll use Portable Contacts http://portablecontacts.net/draft-spec.html (which OpenSocial is aligned with)

For Aspects, we'll use OpenSocial Groups http://opensocial-resources.googlecode.com/svn/spec/2.0/Social-Data.xml#Group (this may need some small modification to make them as rich as D* aspects… namely, whether or not the specified group is publicly listed or not)

For Posts, we'll go with ActivityStreams: http://activitystrea.ms/specs/json/1.0/ which has a schema defined at http://activitystrea.ms/head/activity-schema.html

For Comments, we'll also go with ActivityStreams (see http://activitystrea.ms/head/activity-schema.html#comment)

[rogerz]

+1 on every word ;-)

> aspects� namely, whether or not the specified group is publicly

> listed or not)
>
> For Posts, we'll go with ActivityStreams:
> http://activitystrea.ms/specs/json/1.0/
> <http://activitystrea.ms/specs/json/1.0/> which has a schema defined
> at http://activitystrea.ms/head/activity-schema.html
> <http://activitystrea.ms/head/activity-schema.html>
>
> For Comments, we'll also go with ActivityStreams (see
> http://activitystrea.ms/head/activity-schema.html#comment

> <http://activitystrea.ms/head/activity-schema.html#comment>)

>
>
> To be clear, a lot of the wording above sounds dictatorial-- I did
> not mean it as such, it's just way easier to type that way :) The
> entirety of this post is up for debate, but I hope that we'll stick
> to building a RESTful API based on the existing web standards
> surrounding social services.
>
> Thanks,
> David
>

> --
> You received this message because you are subscribed to the Google
> Groups "diaspora-dev" group.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/diaspora-dev/-/eYb56eDo_vcJ.

[Vipul Amler]

Vipul A.M.
+91-8149-204995

On Fri, Mar 2, 2012 at 5:04 PM, rogerz <rog...@c0unt.org> wrote:
>
> +1 on every word ;-)
>

Awesome +1

>>     aspects… namely, whether or not the specified group is publicly