API overview (pre-release)
Hello Developers!
I want to get the ball rolling on the upcoming API. We've been fielding a lot of private inquiries and I'd like to give a high-level overview of where things are at and where we're headed. A proper knowledge base/faq will be up once things reach a more-or-less steady state.
The API is REST-y.
- All requests are via https, GET for reads, POST for writes (create/update/delete).
- All data is returned in JSON format, utf-8 encoding
Syntax
- GET /?api=v1&token=your-auth-token&method=method-name¶m1=value¶m2=value
- POST /?api=v1&token=your-auth-token&method=method-name [ form data as x-www-form-urlencoded key/value pairs, or json=obj ]
GET Methods (still subject to change)
- auth
- user
- prefs
- tags
- tasks
POST Methods (still subject to change)
- saveuser
- savepref
- savetask
- savetag
- emptytrash
Example Response
{
"build": 999,
"stat": "ok",
"requesttime": 1281021590,
"results": {
"tasks": [{
"id": "12345",
"parent": "0",
"type": "0",
"state": "1",
"suspended": "0",
"completed": "0",
"cancelled": "0",
"seq": "2",
"seqt": "0",
"seqp": "3",
"name": "Call Mary re: plans this weekend",
"tags": "personal,phone,mary",
"etime": "5",
"energy": "1",
"waitingfor": "",
"startdate": "",
"repeat": "0",
"repeatuntil": "",
"repeatfrom": "0",
"duedate": "20100805",
"note": "home phone: (212) 555-1212",
"created": "1280867871",
"updated": "1280948911",
"deleted": "0"
}]
}
}Javascript Same Origin Policy / Cross-Origin Resource Sharing (CORS)
- An optional ?callback=function_name parameter will return the data wrapped as JSONP.
- Response headers are set to Access-Control-Allow-Origin: * for browsers that honor it (e.g. Chrome, Safari, Firefox, IE8)
I've attached a simplified diagram of how we're separating what was one giant tarball of a project into distinct sub-systems.
OK, questions, comments, suggestions, complaints? Let's hear em!
-
logical.png
56.1 KB
logical.png
Showing the most recent page of comments. View the first page
32 Posted by SeaMonster on 02 Apr, 2011 12:46 AM
I know there is a lot in the works right now, but any sign of the API being released? I'm itching for my webOS app with Just Type inbox entry, exhibition mode displays with GPS controlled context filters and full calendar integration for scheduled events.
OK, I can dream, can't I?
Keep up the great work...
Support Staff 33 Posted by David McLaughlin on 05 Apr, 2011 08:53 PM
I'll answer for Elbert here, although he may come back and tell me I'm full of it, since he's the api guy....
Basically, we're pretty much thinking about doing what was in the discussion item #30 here -- an abstraction layer of the api to the cloud scenario.
I know Elbert's super anxious to get working on this, but the reality is that there are some priority things we need to do on the web app first.
So, I can't really give you a timeline at this point, sorry.
David
34 Posted by haeffb on 06 May, 2011 01:20 PM
@haeffb pops in to the API discussion area, looks around, sees nothing new...sets scheduled task to check back in a few weeks...
35 Posted by jimi-b on 09 May, 2011 11:30 PM
Ditto what @haeffb said.
Scheduled
Check Nirvana API progress
@computer x Home x Scheduled > May 29, 2011
low energy
5 minutes required
Due May 29, 2011
Standalone
------- Update 1-Jun-2011 --------- Check Done.
No updates.
Reschedule for next month.
36 Posted by dgtale on 04 Jun, 2011 04:23 PM
Let me know if you need an Android application as pilot for your API.
Many user of my DGT GTD are begging for a sync with Nirvana http://dgtale.uservoice.com/forums/103615-general/suggestions/17074...
37 Posted by beau on 06 Jun, 2011 05:31 PM
As far as I know the API itself exists (minus documentation). The part
that's missing is OAuth--so you'd require the Nirvana user's username
and password (or at least the md5 hash of the password).
The Nirvana website uses the API for everything and if you look at the
source you can see how the list of tasks is retrieved... You could
begin work right now on syncing and then implement OAuth support when
that is released. :)
(I'm just a Nirvana user but I've looked into using the API to gather
data for visualization)
Support Staff 38 Posted by David McLaughlin on 06 Jun, 2011 08:50 PM
N2 runs completely through the api.
An OAuth2 provider, and several server improvements are being worked on before we are going to promote the api to the general community.
Thanks,
David
39 Posted by Artyom on 12 Jun, 2011 05:15 PM
Hello,
Could you please give example how can I get token for API?
I don't find params name for https://www.nirvanahq.com/api3?method=auth
Thanks.
Support Staff 40 Posted by David McLaughlin on 13 Jun, 2011 04:05 PM
@Artyom - When we're ready to start issuing them, we'll let everyone know.
David
41 Posted by veronica on 15 Jun, 2011 03:02 PM
+1 (I just want to be notified if anything happens in this thread.)
42 Posted by NicR_ on 30 Jun, 2011 10:04 AM
Really love the Nirvana Web App - thanks guys!
Am I understanding you right from the note above that there will be different URLs for equivalent GET and POST methods? Doesn't that completely invalidate the RESTful concept, whereby URLs are treated as universal and permanent links to "entities" which are then CRUD manipulated by HTTP commands?
ie
PUT ~= Create (putting a JSON representation of the entity)
GET = Read
POST ~= Update (can optionally support Create-by-parameters too)
DELETE = Delete
So, you might have:
Returns a JSON-formatted list of all task IDs
GET /api/tasksRefers to a specific task by ID, returns JSON blob with all task-related fields
GET /api/tasks/1Find any tasks which contain the string "Dog Food", return list of IDs which match
GET /api/tasks/?s=Dog%20FoodCreate a new Task - throw correct HTTP error code if required fields are missing.
POST or PUT /api/tasks (PUTing a JSON blob or POST params)Update Task with ID =1 setting the tags to be "phone" and "car"
POST /api/tasks/1?tags=phone,carGives a JSON-formatted list of all tags for task with ID=1
GET /api/tasks/1/tagsGet list of Project names (or IDs - but Project names are usually pretty short)
/api/projects/Create new project
PUT or POST /api/projects/Build%20Chicken%20CoopGet a JSON-formatted list of task IDs related to the Chicken Coop project
GET /api/projects/Build%20Chicken%20Coop/Get a JSON-formatted map of task names related to the Chicken Coop project
GET /api/projects/Build%20Chicken%20Coop/names/api/inbox//api/waiting//api/scheduled//api/scheduled/today//api/scheduled/this_week/etc.
JSON-formatted list of IDs for all tasks which are tagged 'phone'
GET /api/tags/phone/Tasks can be moved between tags/projects by:
DELETE /api/tags/phone/23PUT /api/tags/car/23Session handling can still be handled by passing session IDs. What do you think? I'm really keen to get access to the API so that we can start integrating your awesome web app into mobile devices.
43 Posted by scottschulthess on 30 Jun, 2011 10:07 AM
Nicholas is correct, that's the typical way to structure a restful API
44 Posted by haeffb on 30 Aug, 2011 02:41 AM
haeffb wanders by, waves hello, and moves on again...
45 Posted by NicR_ on 31 Aug, 2011 01:10 PM
Hi guys - any movement around this API?
46 Posted by raanraan on 17 Nov, 2011 06:14 PM
The discussion here is all about a data API. How about a GUI API? I like every task to carry a visible creation date, for example. But I doubt this would be popular enough to add as a feature. So I was hoping there would be a way to configure the format of the task line appearance.
47 Posted by Grant on 22 Nov, 2011 06:03 PM
How soon will an official documented API for v2 be available?
Support Staff 48 Posted by David McLaughlin on 01 Dec, 2011 01:46 PM
@Grant - can't give you a specific time, will say it's going to be after the first of the year sometime.
David
49 Posted by tshakah on 14 Dec, 2011 10:14 AM
+1