REST interface

rest.txt

### General requirements

 - Should return 405 method not supported if the components do not provide controllers in the specified format
 - Should work with and without SEF enabled, with and without htaccess
 - Preferably implemented in a plugin so it can be easily disabled
 - Uses OAuth2 for security
 - The REST trigger should be configurable via parameter
 - The format of the returned document is controlled by the HTTP Accept header

### URLs

------------------------------------------------------------

Direct component route (SEF enabled, no htaccess)

http://site.com/index.php/api/component/content/article/1

Indirect route (SEF enabled, no htaccess)

http://site.com/index.php/api/somealias

------------------------------------------------------------

Direct component route (SEF enabled, htaccess)

http://site.com/api/component/content/article/1

Indirect route (SEF enabled, htaccess)

http://site.com/api/somealias

------------------------------------------------------------

Direct component route (SEF disabled)

http://site.com/index.php?option=com_content&view=article&id=1&api=1

Indirect route (SEF disabled)

http://site.com/index.php?Itemid=2&api=1

------------------------------------------------------------



### REST API Rules

A REST API should not be dependent on any single communication protocol, though its 
successful mapping to a given protocol may be dependent on the availability of metadata, 
choice of methods, etc. In general, any protocol element that uses a URI for identification 
must allow any URI scheme to be used for the sake of that identification. 

Failure here implies that identification is not separated from interaction.

Solution:
We solve this by utilizing the support for multiple controller and view formats and by avoiding 
to use the URI for specifying the format and instead using the Accept HTTP header. The API shall
return a 405 method not found if the desired format controller/view does not exist.

--

A REST API should not contain any changes to the communication protocols aside from filling-out 
or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method 
or Link header field. Workarounds for broken implementations (such as those browsers stupid 
enough to believe that HTML defines HTTP’s method set) should be defined separately, or at least 
in appendices, with an expectation that the workaround will eventually be obsolete.

Failure here implies that the resource interfaces are object-specific, not generic.

--

A REST API should spend almost all of its descriptive effort in defining the media type(s) used 
for representing resources and driving application state, or in defining extended relation names 
and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing 
what methods to use on what URIs of interest should be entirely defined within the scope of the 
processing rules for a media type (and, in most cases, already defined by existing media types).

Failure here implies that out-of-band information is driving interaction instead of hypertext.

--

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and 
server). Servers must have the freedom to control their own namespace. Instead, allow servers to 
instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI 
templates, by defining those instructions within media types and link relations.

Failure here implies that clients are assuming a resource structure due to out-of band information, 
such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional 
coupling.

Solution:
We solve this by allowing the "trigger" or resource name used by the API to be configurable, thus giving
servers control over the namespace.

--

A REST API should never have “typed” resources that are significant to the client. Specification 
authors may use resource types for describing server implementation behind the interface, but those 
types must be irrelevant and invisible to the client. The only types that are significant to a client 
are the current representation’s media type and standardized relation names.
ditto

--

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of 
standardized media types that are appropriate for the intended audience (i.e., expected to be understood 
by any client that might use the API). From that point on, all application state transitions must be 
driven by client selection of server-provided choices that are present in the received representations or 
implied by the user’s manipulation of those representations. The transitions may be determined (or limited 
by) the client’s knowledge of media types and resource communication mechanisms, both of which may be 
improved on-the-fly (e.g., code-on-demand).