-
Notifications
You must be signed in to change notification settings - Fork 123
Create a new application
- Decide what app you want to write
- Decide if you're writing an internal or external app
- If internal, copy /App/skeleton to /App/<yournewappname>, rename the skeleton.app file in there to <yourappname>.app, and modify the data therein to applicable values
- If external, set up your app environment/platform
- Decide what data you want. Look up APIs available from those collections/connectors to use
- Query that data, do magical things with it within your app!
There are a few things to consider when writing your first app. Once you decide on these, you're on your way to the fun of hacking cool things atop your own data.
While it's not required, it's a good idea to have a general understanding of how the Locker Project works. If you have no idea about the Locker internals, the next section is a 30 second overview. Skip it if you already know about how the Locker works. :)
There are three areas in a Locker: connectors, collections, and applications. Connectors reach out to third-party APIs and gather information on your behalf. Common connectors exist for popular sites like Facebook, Twitter, and Foursquare--among others. Next, there are collections which collect all of a particular set of data into specific groups. Current collections include contacts, links, and messages. The contacts collection will likely have your Facebook and your Twitter contacts in it, if you've installed both of those connectors. Lastly, there are applications, which can access the data from both connectors and collections, and do interesting things with it. This doc describes how to build an application.
Further reading on the Locker internals here
The Locker allows you to access its information either as an application that runs locally within the Locker instance (which runs on the node.js platform), or as an external application that runs outside of the Locker instance. Either way you choose, you'll always access the data using the API built into the locker.
The Locker Project is still under heavy development, and the auth required to protect your data, as well as to allow access to it to various applications is still being built out. For now, if you have access to the API over the network, you have access to the data within the Locker. Thus Lockers are still considered experimental and in no way should be run on a publicly-accessible machine without understanding the (lack of) access restrictions within!
Remember, you can access connector data and/or collection data. Which one to access is completely up to you. Connectors usually store very specific information in regards to the API it receives its data from. For instance, the Facebook connector will give you exactly the JSON feed that the Facebook API sends to any third-party client. Collections will have groups of the same type from many different connectors, so it makes sense to use collections if you want to see your data across all your connectors. However, sometimes you want specific data from a particular connector, so you can query the specific data you're interested in. Your app can query both if you like, and do whatever magic you wish to do with the results.
Where to find what data is available? Simply start up your own locker, click on Services, and the list there is what's available. Clicking "show unstable" in the upper right will show you all connectors, collections, and applications that are available, regardless of stability. Use the unstable ones at your own risk (or even better, make it work well and submit a pull request!)
Once you decide if you're writing an internal or external app, and determined what data you want, simply look for the API offered by each connector or collection. For collections, you can look in the .js file in the collection directory for the publicly offered endpoints. For instance, for the contacts collection, you would look in Colletions/Contacts/contacts.js. There you'll see an "/allContacts" endpoint. You can query this endpoint to get all contacts from the contacts collection.
For connectors, things are still in a bit of limbo in regards to how you query them directly. At the moment, connectors don't expose their APIs in any standard way. This is a problem, and we are working on standardizing it. So the best bet is to look in the connector itself to see what it exposes via the app.get('...'); routes.
How they WILL work eventually is this; each connector and collection will need to provide a Service Type Definition file. This file will offer all sorts of information about itself, including what API endpoints are available. Documentation is a little sparse for these, but we're working to get this fixed up extremely soon so there is some consistency and ease in writing apps against any service type--be it connector or collection.
Once you query a data source, it would be overkill to constantly re-query it in order to get new information. Instead, the Locker Project emits new events whenever a new event occurs for that service type. If you're writing an internal application, you can listen for events of a type, by calling the locker.listen() function. Here's an example:
locker.listen("photo/flickr", "/photoListener");
This will listen for an event triggered from the Flicker connector, for any events of type "photo/flickr". When an event occurs, Locker will send this event to the endpoint "/photoListener". Pretty easy!
To see the entire list of service types and what connectors and collections they belong to, take a look at the Service Type Definition List.