Where to go for discussion of REST APIs

I’m looking for one or more forums for discussion of REST APIs as a class. Any recommendations?

I’ve found plenty of forms about “web services,” but they all seem to concentrate on SOAP and/or XML. (This one is typical in that respect.) I’ve also found plenty of forums dedicated to particular REST APIs, but that’s not what I need.

You might be overthinking things a bit – rest has won this war partially because it is simple enough you don’t need alot of discussion. Well, unless you really are getting into the finer points of content negotiation and such. In any case, you want to look at places focused on discussing the mechanics of HTTP as that is all REST is at the end of the day.

Unfortunately some of these APIs perform operations that are inherently complex. The complexity is not in content negotiation, but in the content itself. Our existing SOAP APIs reflect this by providing a few calls with dizzyingly complex requests and responses.

I’ve found that I have to fight a tendency to split up each complex SOAP call into many simple REST resources, and then claim that the documentation can be simple because the API has been made simple. It hasn’t; the complexity has just been moved from the resources to the relationships between them. REST API documentation typically doesn’t say much about relationships between resources because there’s little to say, but where the relationships are complex, saying little about them makes for inadequate documentation.

So, I need to devise a format that looks familiar to developers accustomed to REST, but is robust enough to describe unusually complex content and behavior without breaking down.

I want to add a little clarification to my previous post.

I’m not implying that because our SOAP APIs have a few calls with complex requests and responses, the REST APIs that will replace them should be designed the same way. (Simplicity is good, and one of the advantages of REST is that it makes simpler APIs possible).

I’m stating that:

  1. If an API performs a complex service, it’s very difficult to make the API itself simple.

  2. As a rule the REST resources that implement a complex API can be made simple, but not without making the interactions among them complex.

  3. Complex interactions are more difficult to document clearly than complex resources because they have less structure. For the same reason, they may be more difficult for developers to work with even when they are well documented and understood.

  4. For these reasons, an optimal API design for a complex service (or even a passably good design) may well involve resources that are a lot more complex than most RESTed developers are accustomed to deal with.

Ok, I’m really not quite following you – I think you are saying that REST too apis are too complex and poorly documented but that really covers most APIs no matter what the underlying transport is – documentation is the last concern and the guys who can write it well aren’t paid to write docs so they don’t happen.

And yes, the typical pattern of exposing your internal object model over a HTTP interface is not the best option, especially for external consumers. Think messaging over ORM.

We seem to be having a two way communication problem – your post didn’t make much sense to me, either. I’ll try to restate my original question in different terms.

My company has a couple of publicly available SOAP APIs which it is going to re-release with REST interfaces, followed by several additional APIs that will be exposed in REST only. I’m responsible for writing the documentation, which will be used both by internal developers and partner organizations.

I came here to ask what developers like to see in REST API documentation – with specifics, and examples where possible. I’ve looked at the REST API documentation published by several leading web organizations, and I didn’t get a lot of guidance there – in terms of either clear, attractive documentation that I can emulate, or a standard format like JavaDoc that everyone uses with minor variations.

A lot of the sites seem to be based on a sort of “what the heck” approach: “REST APIs are simple, so we don’t have to bother designing the documentation well.” For simple APIs that’s defensible, if not admirable. But our APIs will provide complex services, and so the APIs themselves will unavoidably be complex. I’m concerned about adapting some design because “it’s good enough for {Google|LinkedIn|Twitter|whoever},” only to find that it produces very poor results for our more demanding subjects.

That makes a bit more sense. Actually, I would start with twitter since they actually have a great developer portal: https://dev.twitter.com/docs/api

There isn’t a standard format, I would use the dev team as a sounding board myself.

In general a development team is a good resource, but it has limitations; its members are, so to speak, living on the wrong side of the looking glass. They understand the API forward and backward, so they find it very hard to imagine being an application developer for whom it is a black box.

Twitter was one of the sites I originally looked at. I returned and displayed a randomly selected resource to see what I think of it now. The description of the API itself looked quite reasonable, and I got a little thrill when I saw an example of a complex JSON request, because that’s exactly the type of thing I need to be able to document clearly. I scrolled down to see how they document the message elements… and down… and down… right to the end of the page. They don’t document the message contents!

I’ll be diplomatic and just say I was disappointed. I will continue to search.

I think they document the response object pretty well: https://dev.twitter.com/docs/platform-objects/tweets

FWIW we don’t write much documentation at all about our APIs but rather focus on providing sample code – that is typically what developers are looking for anyhow and it can be much more concise and we don’t need to burden anyone with documentation tasks.