Raw Service Thoughts

• Service Types Overview: The first piece we need to ponder is how we represent service data in a general way. In the Locker Project we use a mime-type like system to document the services. There are higher level primary types such as message, photo, link, and contact. Under these are more specific types that usually represent an external service, or a new complete data structure. Examples of currently used complete service-types are contact/google, photo/flickr and link/chrome. Each service-type is a definition of a set of REST endpoints, the JSON structure they return, and the JSON structure of any events generated. Source: http://blog.lockerproject.org/where-does-my-api-come-from
  • The service type defines the data, not the actual implementation. This means it's the STD.
  • MIME-like. Primary/Secondary i.e. "contact/facebook"
  • Describes storage data, event data, API
  • STD describes the formal definition of the data sent for a given service type
    • https://github.com/LockerProject/Locker/tree/master/Docs/ServiceTypes -- core directory of STDs, should contain a doc for each complete type (noting that a solo primary type is a complete type as well, as in a collection)
  • Example solo primary type: "contact" or "message"
  • STDs should not have versioning
• Moving data from connector to collection space
  • STD has four parts, in connector definitions first two are probably merged based on the primary type shared format and then any extra fields:
    • Shared format data
      • TL;DR: The fields we want a connector to use if at all possible.
      • these are the fields that the primary type implementation (usually a collection), knows how to process in a common way without explicit knowledge of the sending complete type. Usually, these arrive as an event from a connector. They are expected to be the same fields returned in a requested object.
    • Collection-level data
      • these are the extra fields that a collection implementation has generated for a specific object. For example, a Links collection might have the full HTML and a rendered image of the web page available. These are not supplied by the connector at all, rather by user or collection level intent.
    • Action (new concept)
      • Core common actions are create, update, delete, but the list is not predefined. Other actions can be defined but should be carefully considered to not be overly confusing.
    • Event data
      • Data necessary for action to take place. This data is literally what is in the object field of an event.
        • Create: Full object
        • Update: Only diff elements in object from original
        • Delete: Only UID of object to delete
    • API data
      • REST endpoints for
      • Some endpoints are socially contracted to be considered common such as
        • getId - specific object by id, possibly takes an array of ids
        • getAll - all objects
        • Maybe a getAllIds - returns just the ids instead of full objects for pagination reasons
        • getSince - start, stop time range
        • More to discuss on: https://github.com/LockerProject/Locker/wiki/API-Design
• Eventing
  • Overall eventing is a way for services to listen for other services that emit data based on a service type.
  • Basic flow: 0) Services register to listen for service types with the event core * GET /svcId/listen?url=/eventCB
    1. When a service emits an event it sends core the object to emit, the action, and the service type.
       • POST /svcId/event {type:"contact/google", obj:{..}, action:"create"}
    2. Core wraps the object in a simple structure with the id of the service that is emitting the event and the local timestamp that it was processed
       • {via:"twitter", action:"create", timestamp:"2001-11-22T...", obj:{...} } (via is the ID of the me.json file of the connector/
    3. Core POSTs the event to the registered URL listeners
  • Currently, the listen list and currently running emissions is not persisted between locker sessions.
  • Currently, there is no way to pre-service installation register for listeners, so a new service can not start receiving events until it has been started at least once.
• Query Languge
  • current impl is Jison (JSON Bison) https://github.com/LockerProject/Locker/blob/master/Docs/query.jison
  • Specific to API calls above
• Service Startup: Manifest vs me.json vs stdin
  • Manifest: All information necessary pre-installation of a service
  • me.json: The instance-specific data that's originally pulled from the service manifest file. (possible minification/refactor based on only necessary data per instance) {id:"...", serviceSource:"Connector/Facebook"}
  • stdin: Passes all information regarding how communication occurs between the service and locker core. Only working directory, and where to talk to locker core. (possible modification to have service kick back information via URL post callback after receiving stdin boot info. A team look at determining how to handle this more cleanly in regards to data/end events being triggered on stdin).
• Shares and Pipes
  • TBD