[rudder-dev] Establish a naming policy for REST calls

[Matthieu CERDA]

Hello fellow Rudder developpers,

I was thinking about the fact that our REST API, which is young and
needs-driven, has no established naming convention for method calls.

Even if it is not directly a problem, it might become one in the future
and will certainly cause misunderstandings about methods purpose because
of people not understanding names the same way.

We should (as soon as possible) establish a clear way of naming our REST
calls to prevent this.

Here are some of the examples / leads I found on the vast and great
internet:

  * The OVH french hosting provider, which uses a SOAP API for machine
    automation needs.
      o Syntax: service-function-action
          + Example: telephonySmsSend
      o This is not applicable to us (REST vs SOAP) but it gives some
        hints about a possible naming scheme for URIs (
        xxx/rest/core/techniques/reload ? )
  * A complete introduction to this problem:
    http://www.restapitutorial.com/lessons/restfulresourcenaming.html
  * The Atlassian Confluence REST documentation:
    http://docs.atlassian.com/atlassian-confluence/REST/latest/ (note
    the use of versions in the REST URIs)

I hope that these examples will help us to build a consistent naming
scheme that will enable us not to say one day: "Damn it why should I be
forced to read a documentation just to know what this function does ..."

Bye !
-- 
------------------------------------------------------------------------
*Matthieu CERDA*
/Sysop - Netop/
Normation <http://www.normation.com>
------------------------------------------------------------------------
*87 rue de Turbigo, 75003 Paris, France*
Telephone: 	+33 (0)1 84 16 06 01
------------------------------------------------------------------------

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.rudder-project.org/pipermail/rudder-dev/attachments/20121213/33a3bf4d/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: logo-square.png
Type: image/png
Size: 3503 bytes
Desc: not available
URL: <http://www.rudder-project.org/pipermail/rudder-dev/attachments/20121213/33a3bf4d/attachment.png>