API Specification

From Lijst.com Wiki

Status: draft

Version: 0.1.3

Lijst.com is a tool to keep track of personal values: body weight, training results, anything measurable. It should be possible to gather these values with as less human effort as possible. The Lijst API facilitates this automated gathering by third party solutions.

Scenario's

1. A user wants to add data to Lijst.com using her PDA. The app on her PDA (Client) should be able to identify the user to the Service.
2. A third party website (Client) wants to integrate Lijst.com data for a user of both Lijst and the Client

Anyone with a Lijst account can use the API. Please read our API Terms of Service.

Functionality

Currently only manipulation of existing accounts

Changes

• 2009-03-14 v0.1.3 (not yet released) Deletion of Measurement and List. Added an is-datetime parameter to Measurement calls.
• 2009-02-17 v0.1.2 Added the List id to the response in the Read and Create calls. (R.R. Nederhoed)
• 2009-02-16 v0.1.1 accessible via www.lijst.com (as well as beta.lijst.com) (R.R. Nederhoed)
• 2008-12-10 v0.1.0 Lists: Read, Create, Measurements: Read, Create. (JV)

List

• Read
• Create
• Delete
• Update (TODO)

Measurement

• Read
• Create
• Delete
• Update (TODO)

Technical solution

To get access to a resource you must provide proper credentials using http Basic Authentication. All communication is done using JSON. The resources table below has examples of possible JSON structures.

RESTful Resources on Lijst.com

Base URL: http://www.lijst.com/api/v1/

List Manipulation

ex.	URI	Method	Functionality	POST data	Example data
i	{username}/	GET	Lists of given user	-	{"lists": [{"href": "/api/v1/wadama/1/", "name": "Razor", "id": 1}]}
ii	{username}/	POST	Create new list for given user	{"name": "Razor"}	{"href": "/api/v1/wadama/1/", "name": "Razor", "id": 1}
iii	{username}/{list}/	DELETE	Delete the given list	-	{}

Measurement Manipulation

ex.	URI	Method	Functionality	POST data	Example data
i	{username}/{list}/	GET	Measurements in given list	-	{"color": "#303090", "measurements": [{"timestamp": "2008-01-02T00:00:00", "is-datetime": true, "value": 12.0}], "name": "Razor"}
ii	{username}/{list}/	POST	Create new measurement	{"value": 12.3}	{"timestamp": "2008-01-02T16:03:52Z", "is-datetime": true, "value": 12.3}
iii	{username}/{list}/	POST	Create new measurement	{"value": 9999.77, "timestamp": "2009-03-14"}	{"timestamp": "2009-03-14T00:00:00Z", "is-datetime": false, "value": 9999.77}
iv	{username}/{list}/	POST	Create new measurement	{"value": -234, "timestamp": "2009-03-14T21:58:59+01"}	{"timestamp": "2009-03-14T20:58:59Z", "is-datetime": true, "value": 12.0}
v	{username}/{list}/	POST	Create new measurement	{"value": -234, "timestamp": "2009-03-14T21:58:59+01", "is-datetime": false}	{"timestamp": "2009-03-14T20:58:59Z", "is-datetime": false, "value": 12.0}
vi	{username}/{list}/{measurement_id}/	DELETE	Delete the given measurement	-	{}

The example data for each GET message indicates what kind of data can be expected in the response. For the POST messages this would be the request body. A response to a POST message contains a JSON formatted representation of the resource that has been created.

timestamp

according to ISO-8601

UTC in example iv and v: "2008-01-02T16:03:52Z", "2009-03-14T22:08:33Z"

with timezone in the request of example vi: "2009-03-14T21:58:59+01" (and UTC in the response)

is-datetime

use false to indicate a date value. true for a regular timestamp

Possible future features

General

• Error handling!
• Status
• Search Users
• Search Public Lists

User

• Authentication
  • Developer key (Needed?)
  • OAuth integration (TODO)
• Last login (Needed?)
• Lists

References

Definitions

API

Application Programming Interface

Client

Software calling the Lijst API

Developer key

Identifier giving access to anonymous

List

Collection of Values

Service

The Lijst.com web service

User

Lijst.com account holder

Measurement

A dated value

Resources

• RESTful Resources
• Flickr API
• OAuth Specification