Build a RESTful API for Piwik

[tsteur]

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.

[czolnowski]

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 "?" ?

[tsteur]

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

[diosmosis]

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.

[mattab]

Maybe we can push this for Piwik 3.0. It's related to other powerful ideas:

• Make JSON the default format for the REST API.
• Build a JSON version of the Tracking API Tracking API: provide a new JSON Tracker API #4625

[mattab]

I'm watching this nice writeup video about REST+JSON API design (changed speed to 1.5x 👍 )

there are two types of resources

• Collection Resource eg. /applications
• Instance Resource eg. /applications/a1b2c3

Behavior is specified using HTTP methods: GET, PUT, POST, DELETE, HEAD

How to choose the API version?

• in the URL eg. /api/v1/... practical and easy,
• or use the power of media-type /application/json+foo;application&v=1, maybe too complex?

other best practises mentioned in the video:

• use camelCase for properties and functions
• Date/Time/Timestamp: advertise and use ISO 8601 notation
• in all resources response, add a property href containing the URL to get this resource
• Optional: response body to POST requests may contain the resource representation when feasible. Add override ?_body=false for control.
• Listen to Accept header to see which format is requested by client
• Reference expansion, to load a given nested resource eg &expand=directory to see directories in which a user belongs to.
• Partial representation, choose which fields i'm interested in, eg. &fields=givenName,surname,directory(name)
• Support offset and limit parameters (as shortcuts to filter_offset and fliter_limit)
• For many to many relationship, create a new Resource for the relationship. eg. Groups have several accounts and an account is in several groups. Create /groupMemberships resource.
• Make Errors very clear, eg. following fields: status, code, property, message,
  developerMessage, moreInfo (link)
• Security: use existing protocol: oAuth 1 (more secure), oAuth 2 OAuth2 / oAuth plugin for API authentication #906, Basic over SSL
• Caching: Etag http caching is very practical

[tsteur]

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

[mattab]

from #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