This is a planning/discussion ticket:

Background:

• Piwik uses Reflection to expose a REST API.
• Piwik uses phpdoc tags (e.g., @param), but these do not influence runtime behaviour.

Example from Actions/API.php:

        /**
         * Returns the list of metrics (pages, downloads, outlinks)
         * 
         * @param int $idSite
         * @param string $period
         * @param string $date
         * @param string $segment
         */
        public function get( $idSite, $period, $date, $segment = false, $columns = false)

Gaps:

• we don't use the type hinting in @param for error messages or validating the API method's parameters
• when it gets tricky, we see developers fall back to using Piwik_Common::getRequestVar()
• it can't accommodate adding/removing/renaming a parameter without breaking backward compatibility
• Controller methods are not similarly exposed
• the Reflection API has overhead; why don't we cache metadata?

Proposal:

• make use of annotations to actually influence runtime behaviour
• use the Addendum library; it's LGPL and it doesn't require php 5.3
• annotate a class or method

Phase 1:

• feature would be disabled by default
• adds annotation-based security
• default to all if no @access specified
• allow all methods if no @method is specified
• unspecified @param is passed through without validation/filtering

Phase 2 ("secure by default", i.e., break 3rd party plugins that haven't been updated):

• feature is enabled and cannot be disabled
• default to no-one if no @access specified
• disallow all methods if no @method is specified
• unspecified @param is discarded
• validated/filterd parameters are injected via $this->request (instead of our wrapper around $_GET/$_POST)

Possibilities:

Applies to class or method:

• @access("SUPER") - is superuser
• @access({"VIEW", "ADMIN", "SUPER"}) - has at least VIEW access

Applies to class or method:

• @method("GET") - restrict access to this method to HTTP GET
• @method({"GET", "POST"}) - restrict access to this method to HTTP GET or POST

Applies to all methods of a class:

• @param(idSite={assert="int", default=1}) - optional idSite; defaults to 1
• @param(referrerUrl={assert=@type\LocalUrl}) - required referrerUrl must be a valid local URL, validated by Piwik_Annotation_Type_LocalUrl
• @param(newSiteUrl={filter=@filter\Url}) - required newSiteUrlis filtered by Piwik_Annotation_Filter_Url

For methods, either use the @param annotation above, or apply to the preceding @param for a method using:

• @default(1)
• @Assert\LocalUrl()
• @filter\Url()

References:

• http://piwik.org/blog/2008/01/how-to-design-an-api-best-practises-concepts-technical-aspects/
• http://code.google.com/p/addendum/ (see also doctrine-common's implementation)
• http://code.google.com/p/stash/ (for caching)
  Keywords: interesting