api

"REST vs. SOAP" has been an ongoing battle for quite a while, in the tech industry. There is a seemingly upwards trend of the number of open RESTful APIs emerging vs. the SOAP ones. It's probably safe to conclude that, at least among open APIs, REST is winning.

The problem, however is the ambiguity of the answer to the basic question: what is REST?

RESTful API Design

Representational State Transfer (REST) is an architectural style, for distributed hypermedia systems. It was initially defined in 2000 by Roy Fielding in his doctoral dissertation. REST is based on the concept of transfer of representations of resources. A resource is any application entity that can be uniquely addressed with a Uniform Resource Locator (URL). A representation of a resource is a document that captures current or intended state of a resource.

Since REST is an architectural style not: a well-defined specification, it leaves a lot for interpretation. However, with the increased proliferation of the RESTful style in popular web APIs, some common traits have emerged which are now recognized as best-practices in RESTful web API design. REST, in theory, is not limited to the web, but for the purposes of this blog post we assume to be discussing REST in the context of the world-wide web.

Basic Principles

• Proper RESTful APIs extensively utilize HTTP Protocol. Usage of HTTP methods for CRUD, standard HTTP response codes, common HTTP headers and Mime Types is a common practice.
• URLs in RESTful APIs are semantic, resource-centric and have a general structure which looks something like the following:
  

  http://api.example.com/{ver}/{lang}/{resource_type}/{resource_id}.{output_format}?{filters and api_key as arguments}

  where:

Blog post about the new World Bank API, how we designed it, why we are excited about it and why you could be, too:
http://www.agileapproach.com/blog-entry/world-bank-api-20-launch

Drupal requires its source documentation to be compatible with DoxyGen. If you are working on a large project, you want to install DoxyGen and run it on cron to have nice, up-to-date API docs.

Unfortunatley, if you install Doxygen via yum (or any other auto-updater, I assume) it installs a fairly old 1.4.x branch that is incompatible with Drupal. Specifically, it completely ignores the .module and .install files and has poor support for .inc, from what I can tell. That's because Doxygen does not realize these are PHP source files.

What you want to do is to install the latest Doxygen release (1.5.8 at the time of this writing). In the new version, the author of Doxygen has generously added a configuration tag that allows mapping of arbitrary file extensions with language types. The setting you need in your doxygen configuration file is: