Open tsteur opened 9 years ago
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
/applications
/applications/a1b2c3
Behavior is specified using HTTP methods: GET
, PUT
, POST
, DELETE
, HEAD
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:
camelCase
for properties and functionshref
containing the URL to get this resource POST
requests may contain the resource representation when feasible. Add override ?_body=false
for control.Accept
header to see which format is requested by client&expand=directory
to see directories in which a user belongs to.&fields=givenName,surname,directory(name)
offset
and limit
parameters (as shortcuts to filter_offset
and fliter_limit
)/groupMemberships
resource. status
, code
, property
, message
,
developerMessage
, moreInfo
(link)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
from https://github.com/piwik/piwik/issues/6158
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
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 orindex.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.