RecAPI

RecAPI.md

Recommendation Engine API Documentation

Notes

• Anything enclosed in parentheses is an OPTIONAL variable field.
• Everything preceded with a colon, ':', is a necessary variable field.
• Server hostname is omitted for clarity and brevity.

#User API :

• POST /api/users -- Creates a user

• PUT /api/users/:dijit_id -- Updates a user

  • This would be called whenever a user decides to link a service to Dijit, such as Netflix or Facebook. Still working out internal request params.

• DELETE /api/users/:dijit_id -- Deletes a user

• GET /api/users/:dijit_id/(:query_params) -- Return user information

  • Including a list of optional params to cull down what we want to see at any particular time. This leaves things flexible.

#Recommendations API

(Note: :u_id and :r_id are both Dijit IDs here, of the user and media entity respectively) I know these few routes aren't totally RESTful (it ought to be /api/users/u_id/recs/r_id or something like that) but I wanted to keep the idea of managing users and
managing recommendations separate and this made sense in my head. I'm open to discussion about this.

• GET /api/recs/:u_id -- Get a set of recommendations for the user. Might include an optional limit and other query variables.

  • Response JSON would look something like this:

  { u_id: .... recs: [ {dijit_id: .., score: ..} {dijit_id: .., score: ..} .... ] }

• POST /api/recs/:u_id -- Requires a param media_ids in POST that consists of a set of Dijit IDs. Will return a sorted list of those IDs scored by relevancy to the u_id.

MediaEntity API

• POST /api/media_entities -- Creates a MediaEntity

• GET /api/media_entities/:dijit_id/(:query_params) -- Returns info about a particular MediaEntity.

  • Including a list of optional params to cull down what we want to see at any particular time. This leaves things flexible.

• PUT /api/media_entites/:dijit_id -- Updates a MediaEntity

  • This would be called to connect metadata for a media entity, like an actor to a movie, etc

• DELETE /api/media_entities/:dijit_id -- Deleting a MediaEntity (will probably be rare)

• GET /api/media_entities/trending -- See TRENDING MediaEntities

  • Special call to get a set of 'interesting' current things in our DB. This could be things that have seen a lot of recent links, or lot of activity, or just our most popular.

Error messages

I stole the error response JSON format from Github's v3 API because I liked it. It was flexible enough to handle most of the API call errors that I could think of and small enough to express everything well without being overbearing. An error response may contain multiple errors. Every error has a resource, a field, and a code. The resource corresponds to what model was trying to be manipulated, the field is what was wrong regarding the interaction with the model, and the code is how that interaction was wrong.

The only codes are: missing_resource -> resource that's being referenced is missing or doesn't exist missing_field -> field isn't specified or doesn't exist invalid -> tried to set a field to something bad already_exists -> the resource you're trying to add exists already

For more info on my thinking: http://developer.github.com/v3/ (the errors section)

JSON:

    { message: ""
      errors: [ { resource: "",
            field: "",
            code: ""},
           ....
        ]
    }