Update server API spec documentation

[ijdoc]

We will be writing:

• Raw observations (will be private in our own server implementation)

We will be reading:

• URNs (public, payload is raw observation)
• Relative distance between URNs (payload is two URNs)
• Relative distance between raw observatinos (payload is two raw observations)
• Neighbouring URNs (payload is raw observation or URN, plus max count)
• Fingerprint centroid (will be private in our own server implementation)

We will be deleting (not confirmed yet):

• Raw observations (will be private in our own server implementation)
• URNs (will be private in our own server implementation)

Nothing to edit at this point

We will NOT be dealing with tags nor locations at all, so the corresponding end-points should be somehow marked as not implemented

[elyas-bhy]

Can we also clearly specify the description of the following items?

• Raw observation
• URN
• Fingerprint
• Fingerprint centroid

As for neighbouring URNs, what exactly is the "max count"?

[ijdoc]

• raw observation: the list of access points with strength level as seen by the client device
• URN (unique resource name): the unique identifier (string) generated by the engine. When referring to the server, we are talking about the global URNs. URNs generated locally by the client device are never sent/stored to/on the server
• Fingerprint: fingerprint centroid: The normalized representation of a raw observation used to retrieve URNs and compare indoor locations.
• Fingerprint centroid: A fingerprint when stored on the server AND associated to a URN (because it represents a collection of neighbouring fingerprints that have been 'collapsed' into it)
• Max count: how many neighbours the developer wants to obtain (there may actually be less on the database, that is why this is a max)

[elyas-bhy]

I have posted an initial draft of the API description here: http://wiki.mobile-accessibility.idrc.ocad.ca/w/Tagin!/Tagin_API
Please review it and let me know what to change (some items are missing).

Just to make things clear, in the previous implementation a "fingerprint" consisted in a collection of beacons. Should this stay the same, since scan results provide multiple beacons?
Also, a URN is just an identifier for a centroid, correct?

[ijdoc]

To answer your question, the only difference between raw observations and fingerprints is that the former list has strengh measurement s as reported by the client device in dBm, whereas the latter has normalized signal strengths as calculated by our engine as a relative unit going from 0.0 to 1.0

Both are lists of access points.

[ijdoc]

Imported API wiki page into github. @elyas-bhy let's work within the github wiki from now on.

[ijdoc]

@elyas-bhy updated API spec... take a look and comment if you think it needs editing (e.g., may not comply with RESTful principles):
https://github.com/idrc/tagin/wiki/tagin!-API

[elyas-bhy]

I suggest the following changes:

• /POST ~/patterns instead of /POST ~/tag: we are adding a Pattern to a collection of patterns, so it only makes sense to use that collection in the URL (why use the term "tag"?).
• Add URNs/ prefix to neighbours, distance and delete endpoints: same logic as above. This allows us to have a better structure (we wouldn't want to manipulate instances at the root of the URL). It is more intuitive to follow the design collections/instance.

I'm by no means an expert in RESTful design, so let me know what you think of it!

[elyas-bhy]

One more thing: shouldn't the POST request be public?