The Linccer API
The Linccer API is intended to connect arbitrary devices on the same location. The devices do not need to be in the same local network or use a common connection type, they just need to share the same (geo) environment. Our server uses environment information, like gps coordinates to detect the devices that should be grouped:
The Hoccer Utilities
The Hoccer Utilities (jet to release) are build on top of Linccer to provide a common protocol for sharing files and content:
Which parts should you use?
Depending on your needs, you have to decide which parts to use.
You want to connect your Apps
The Linccer API allows to transfer arbitrary JSON data between the grouped devices. This allows high flexibility in what to share. Just transfer the data that best fits for your app. If you write an App for passing urls you can just send { url : "http://hoccer.com" } or similar. Of course receivers must know the choosen lingo. To keep the sharing experience smooth and fast, the JSON should not be to large. If you want to pass larger content like images you can use our FileCache and transfer only the generated uri’s with Linccer.
You want to offer a file sharing App
In addition to the plain linking API we soon offer a Hoccer transfer spec. Hoccer is our popular file sharing App currently available for iPhone and Android. It aims to simplify data sharing between devices. All Apps complying with the Hoccer spec can exchange data between each other.
Actions
A Linccer transaction consists of two actions, a send action and a receive action. For example the Hoccer App uses the throw and catch metaphor for triggering these actions.
Currently both actions have to be performed (nearly) simultaneously. The way to trigger the actions is up to you. Some Apps may use buttons, others may require the users to bump their phones together.
Action Modes
Actions modes determine how many devices can share and receive simultaneously in the same environment (eg. group). If the constrains are violated no transfer will happen at all. To make sure no other devices interfere actions may take some seconds to perform successful. If your App does not need secure transfer, drop us an email to change this behavior.
One-to-many
A one to many connection lets you distribute content from one device to several others. If two or more shares are triggered almost simultaneously in the same environment (eg. group), a collision error (Status Code 409) is send to all participants.
One-to-one
This mode ensures a one-to-one transaction between devices. If two or more shares or receives are triggered almost simultaneously in the same environment (eg. group), a collision error (Status Code 409) is send to all participants.
RESTful API
The Linccer API is a RESTful webservice. So if your favorite language has a http library (most have) you can easily connect to our service.
For convienence we offer higher level APIs in Objective-C, Java, Ruby, JavaScript and more (see our GitHub page).
Even when you plan to use one of the higher level API implementations, you should read the RESTful Flow. It will give you a better understanding of how the Linccer API works.
API Commands
All commands require a self generated client-id which is simply a UUID like 1122ffaa-8c99-49ee-b045-33d737cc50f9. We recommend to keep the same uuid between sessions to make environment updates all more efficent.
PUT https://linccer.hoccer.com/v3/clients/[client_id]/environment
As mentioned above Linccer groups clients based on the environment. Currently an environment consists of the clients location (latitude, longitude, accuracy) and the bssids around the client:
{"gps":
{"accuracy":280,"longitude":13.409,"latitude":52.516, "timestamp":1291816828},
"network":
{"accuracy":650,"longitude":13.408,"latitude":52.517, "timestamp":1291644002}
"wifi":
{"bssids":["00:22:3f:11:5e:5e","00:22:3f:10:a8:bf"], "timestamp":1291644028},
}
To allow a fast coupling, groups are created before the exchange is triggered. You must PUT the environment to our server and you are only allowed to exchange data afterwards.
You should also continue to watch changes in the environment and send another PUT request for each change.
Our Hoccer App starts sending the environment just after the startup. For other apps it might be more appropriate to start the environment updates when the user enters a sharing mode, but that depends on the type of your application.
PUT https://linccer.hoccer.com/v3/clients/[client_id]/action/[ one-to-one | one-to-many]
To send data PUT a valid JSON string to the action uri. Send the data as JSON in the Request-Body.
GET https://linccer.hoccer.com/v3/clients/[client_id]/action/[ one-to-one | one-to-many]
To receive data perform a GET request on an action uri.
The arrival order on the server is not importend. They just hava to arrive within three seconds.
API Keys and authentication
To make sure the Linccer actions of your App does not interfere with other Apps, you need to register for an API Key and use it for in all your requests. To simplify the try outs we use and demo API Key in all code examples on GitHub page. But as soon as your implementation get’s serious we recommend to switch to an own key!
FileCache
If large files need to be transfered between devices you can use our FileCache to store the data temporary in the cloud. For example POST <multipart data> http://filecache.hoccer.com/?expires_in=60 will return an uri where the posted file is available for one minute.
How to continue?
If you want to use Linccer in your App, read the appropriate reference (JavaScript, iOS, Java, Ruby, Android, C#/.Net).
If you want to write a Linccer Client in another language or platform read the complete RESTful specification.
If you want to connect your app with the Hoccer File Sharing Ecosystem, read the Hoccer Utilities spec (jet to come).