The idea for this would be to write a new plugin on top of the current API. This would bring the advantage that the old API stays untouched / backwards compatible (and maybe we could deprecate it in the next major version 3.0).
Since we want to separate the back end from the front end in the long term having a RESTful API becomes more important.
When we talked about this last week we figured out one of the challenges would be rewriting the URL from
/api/... to the actual plugin file or
index.php because not all users are using Apache (easy with .htaccess if rewrite is enabled). Unless we do not find a better solution people will have to modify their server config in case they want to use it.
So module and action should placed like /api/:module/:action and rest of required parameters (most of reports required idSite, date, period) should be set as GET parameters after "?" ?
It wouldn't be exactly :module/:action I reckon. It be probably rather something like
/api/users/ . Haven't thought about it so much yet
RESTful APIs are built around resources so /api/:module/:action would still be RPC. I think something like /users/:id_or_name, /reports/visitsbybrowser or /visits/reports/bybrowser (ie, /:entity/reports/:dimension where reports is a resource related to visits) would work. /api seems unnecessary to me.
Maybe we can push this for Piwik 3.0. It's related to other powerful ideas:
I'm watching this nice writeup video about REST+JSON API design (changed speed to 1.5x :+1: )
there are two types of resources
Behavior is specified using HTTP methods:
How to choose the API version?
/api/v1/...practical and easy,
/application/json+foo;application&v=1, maybe too complex?
other best practises mentioned in the video:
camelCasefor properties and functions
hrefcontaining the URL to get this resource
POSTrequests may contain the resource representation when feasible. Add override
Acceptheader to see which format is requested by client
&expand=directoryto see directories in which a user belongs to.
limitparameters (as shortcuts to
If someone is not aware of this topic there is also this GitHub project providing a summary and some links to more information: https://github.com/WhiteHouse/api-standards
The link in the title is a list of HTTP API guidelines used by Heroku. It may have many useful ideas that can be implemented in Piwik.
Foundations Require TLS Version with Accepts header Support caching with Etags Trace requests with Request-Ids Paginate with ranges Requests Return appropriate status codes Provide full resources where available Accept serialized JSON in request bodies Use consistent path formats Downcase paths and attributes Support non-id dereferencing for convenience Minimize path nesting Responses Provide resource (UU)IDs Provide standard timestamps Use UTC times formatted in ISO8601 Nest foreign key relations Generate structured errors Show rate limit status Keep JSON minified in all responses Artifacts Provide machine-readable JSON schema Provide human-readable docs Provide executable examples Describe stability