Gathering API v0.1 ideas


#1

We’re starting to think of what to include in our first version of API, and suggestions are welcome!

I’ll compile a list of most popular ideas in the main thread and hopefully that would avoid suggesting duplicates. When requesting an endpoint or API feature, it’s always helpful to explain your use case (what you imagine using it for), that way we can understand your need better.


P.S. While working on Dynalist, we’ve dealt with some APIs: Dropbox, Google Drive, and Google Calendar, and I’ve heard my fair share of @Shida’s complaints about how unforgiving Google’s APIs are… Hopefully, as individual developers ourselves, we will constantly remind ourselves of this and make something easier to use for you guys!


Api
#2

Are you making a distinction between client-side API and server API?

Having some sort of client-side JS api will help making bookmarklet/userscripts easier (e.g. vim keybindings).

For server-side, it would be great to have an ability to build dashboards. E.g. let’s say I have my projects’ todo list inside Dynalist, I add items there and sometimes check them off. Having an ability to query that info (all children of a particular node (maybe selected by tag or set of tags) with their add/edit/check dates for date >= X (to allow asking only for updates)).


#3

Something I’d love to see is an API:

  • List documents
  • Search for location (similar to move button’s search)
  • Create/edit a note
  • Bulk creation of notes might be nice

For my use case, I’m writing a tool to distribute the things coming at me between a todo app, calendar, and dynalist (which I treat as the place where all my information goes). When deciding to put something in Dynalist I need to be able to pull back where it could go to and then save that there.


#4

For now, we’re talking about a server-side API that’ll be REST like. We will get back to the JS client side API/plugin system slightly later, possibly after the server-side API is fully launched.


#5

I’m not a developer, but I’d like to see it be useful in a way which information could be fetched via a Telegram bot. So something that could grab the creation/modification times, link to the bullet point, and (of course) bullet content would be great.

Telegram supports bots sending hyperlinks in messages, so files and pictures shouldn’t be a problem (fwiw).

So in real life, I would just type, “@Dynalist_bot chocolate chip cookies recipe” and then results would load above (if it were an inline bot) and then I’d just select the result I needed. Of course, I understand that building an API =/= building a Telegram bot. I’m just trying to provide a visual.


I guess it’d be cool to access the file manager as well, so that way developers could represent files as they please, and hopefully it’ll be adopted upstream.


One thing I’m guessing that might be important is having an upper limit so that way a developer doesn’t go broke due to some error or heavy use (assuming they’ll be charged for the API’s use).


#6

I’ve just started using Dynalist and love it! I’m really looking forward to the API :slight_smile: Thanks!

Use scenario: I’m using dynalist as a way to organize features/specifications. Features can be tagged with owners and with stages of development (backlog, progress, done, etc.). I would love to be able to write a script that automatically syncs my dynalist outline with a trello kanban like board. Trello is commonly used as a way to visualize progress in a project. But I feel Dynalist is better at showing a hierarchical / organized representation of all the things that need to be done as a project grows.

APIs:

  • Would be great to be able to GET a structured representation of any subtree within a Dynalist document (of course including the document as a whole). Main thing I’d need is the id, text,tags of each node. For my current need, I don’t believe I need a hierarchical representation, just an array of objects representing each node. But I would need to be able to get the array of objects corresponding to each distinct node (so I could create trello filters that show the kanban board corresponding to a subtree).
  • Would need to be able to POST/PATCH tags and text to specific nodes within a Dynalist document.

#7

I believe tags are just part of text right now, and we only start parsing tags at the UI level. Might make that API endpoint a bit challenging.


#8

Ahhhh, got it. If I can just get the id and text of each node, maybe I can parse the tags myself. So then I would just need:

  • GET which allows me to get the subtree of objects for any specified node, where each object has id and text,
  • POST/PATCH which allows me to change the text of a particular node in the tree.

#9

Oh yes, also if it’s possible to have a webhook that let’s us know when text for a given node has changed, that would be great too!


#10

Not sure if that’d involve a lot of server load, @Shida?


#11

Yeah, it’s unlikely we can provide that level of granularity at our current scale. The only thing we might be able to offer is a websocket based push system that’s granular to document being changed.


#12
  • Create Note. Details: document, list, bullet, bullet note.
    Use case: option (via IFTTT etc) to dynamically create notes
  • Note Created. Details: document, list, bullet, bullet note, perhaps ID
    Use case: use as trigger (IFTTT etc) to make a “recipe” of IF note created (conditions) THEN other action
  • File Created
    Use case: trigger (IFTTT etc) to make a recipe of IF file uploaded THEN other action (e.g.: upload it to dropbox)

#13

Got it, I think that can do for now! :slight_smile: Thx!


#14

This might not be the right place to ask this, but I’m also wondering, is there a place where I can get the entire text of a document right now? Just a string with new lines for each separate bullet point?

If so, that’d be super helpful so that I could create a script that processes that text and generates the corresponding trello view. Before the API comes out, I’ll just make it so edits only happen on Dynalist, and I’ll re-run the script every day or so.


#15

@Shida is more qualified to answer this one :slight_smile:


#16

I agree with David Lee’s post here

★ 1:★ get / post parent and child to batch process notes

I would like to a * GET and *POST / PATCH to for a specific ID and its child ID / nodes, for text

This way you can send a GET request to a parent ID, and then POST update anything in the child ID’s contents

I could specify which parent ID I would want to work with, so I update information at whatever location is relevant

So this would let me parse the data easier. For instance, the !date parameters are not tag clickable. Ideally I want to timestamp the week number next to it automatically, e.g. #W16A for week16. I usually don’t phrase express this and do it after the fact, to make it easier to search overall

Going back to this GET POST request thing again. This would also let me parse my imgur URL links, so I can natively tag my image links right inside dynalist. Basically, I’ll have a bunch of text + an imgur link. I can assign metadata to my images, so I can download all my image links, and automatically assign metatags. This way, I can search my adobe-bridge locally for all my images via text tags as well. Would be super awesome for me to manage my 7000+ image / gif library with imgur+sharex

Adding on, to this GET POST request thing. Now I can rearrange so on my bulletpoints, all my imgur link appear first, then any tags associated with it + words associated with it. This would make my notes significantly easier to read. This could also applied to files uploaded with dynalist Maybe you might want to parse all your data so the uploaded file link appears at the beginning or the end of bulletpoint

BASICALLY API enable GET / POST request for parent-child relationships nodes, to modify data, parse it in any format, reformat information afterwardsd so its easier to search and look at, etc



★1.1★ : Parsing data expanded into spreadsheets (Replaces python scripting)

Because in the trello project roadmap, you are going to implement ?some form of markdown table support?
so we can have tables down the road on specific lists

Sometimes I want to take notes on different vendors and clients. I currently do not use dynalist for this at all, because of lack of table support. I need to add the ✪ vendor name → ✪ discount structure ✪ freight notes ✪ PO contact ✪ Quote request email, etc

This is kind of hard to explain, but the API should enable me to do the following:

  • (pre - markdown table support) I’ll have some parent / child nodes outlined - I should be able to create a spreadsheet of data from this. The parent node is the first column, and child nodes in a specific order are each value in subsequent columns.

  • (pre-markdown table support) Or a specific formatting convention I use on my bulletpoints, to delimit cells like comma seperated values CSV. I usually use ✪ Bulletpoint 1, ✪ Bulletpoint 2, ✪ bulletpoint 3. I want a table with this data

  • (Post-markdown table support) - this feature would make this API portion redundant I think, but would help make longer text tables possible

BASICALLY - this part is hard to explain since I don’t know how to phrase it correctly, but by parsing data, I could create spreadsheets of data with it (rows, columns ,etc) based on parent-child relationship nodes, and the order of how child notes appear, or specific keywords in the child node.

BASICALLY 2.0 see diagram explaining it

ALTERNATIVELY I could also create gantt charts as well, there basically just spreadsheets too. Or integrate with trello based on keywords, etc etc



★2★ dashboard javascript / chrome plugin / workflowy rawbytes methods / specific view modes / data analysis

I would use this for a lot of already-made workflows by rawbytes plugins from workflowy. Resource here:

https://rawbytz.wordpress.com/

  • calculate how many tags this appears on a dashboard extension
  • how many times I used “ABC” word
  • how long my texts are on average
  • How much I wrote per day
  • How many image links I made throughout day
  • Mind map relationship mapping between parent / child nodes
  • Where is my deepest child node at?
  • How much time did I spent in that specific view mode ?(so I can analyze what improves to make)
  • How much time did I spent on dynalist, based on node creation dates / node updated dates? (To calculate pomodoros)
  • automatically calculate pomodoros based on node creation / updated dates


★3★ Automation via IFTTT using special command phrases

Everything here is basically just doing the following:

Not all tags are rated equally in my mind. Some tags are more important than others, and I want them to have some powerful features associated with some

This is already done with the “!” operator into google chrome

But, I might want some that implements special javascript functions like “ScrollTop”, etc so I can click instead of pressing “CTRL+F” to find keywords in a specific list view

It all goes back to this feature requests I made:, about implementing special scrolling $tags

So what things would I use with special keywords / tags?

  1. Javascript scroll navigation functions (e.g. Scrolltop) when clicked on
  2. H1, H2, H3 tags can appear on a right-pane similar to app.classeur.io
  3. @to-do tags can appear on a dashboard to the right, and set to expire (or delete itself) at certain time frames
  4. A @FollowUpThen system email system (https://www.followupthen.com/) can be implementing, for managing someday type tasks based on keywords (e.g. @Future-me). Basically, instead of an email, you would get a javascript popup dialog box showing all your @to-do tasks. If the task is done, you checkmark the @to-do panel . this lets you have a retroactively global KANBAN to-do list anywhere you want, all in a flatflowy style appearance, using a tabsnooze (chrome plugin) / followupthen style deadman’s switch do this task or we’ll keep bugging you until its done

Adding onto this idea num4 that I just made up

You can specifiy certain popup windows to appear at certain specified times using the API

The dashboard program would behave systematically like this:

  1. Every hour, search all @todo tasks and @someday tasks regardless of where note is at
  2. Once/day or whatever time set, popup a javascript dialog box with a checkbox of all items
  3. For someday tasks, make it appear once a week with a checkbox of all the items
  4. If an item is checkedoff, have the @todo tag at that task bulletpoint deleted (just the tag) (or CTRL+ENTER) the information

Diagram flow of this:

Then there’s the obvious use cases that other users had mentioned, IFTTT this and that etc


Use of colours besides priority
#17

My main use case would be exporting certain items and displaying them in a custom format. I’d like to select items based on criteria, such as:

  • which document they are in
  • due date
  • parent
  • tag
  • text in the item or its notes
  • whether the item is checked

Anything which makes it easier to filter or parse items would help, but I also think it might be best to just keep it simple and allow the API to grab all the items in an efficient way (without requiring multiple API calls). The program that calls the API can then read the attributes and do any filtering.

I need addition to this, a simple polling or notification mechanism to easily identify changes would help. For example, I might want a program to trigger on a certain event, such as the completion of an item. I don’t want to grab all the data and work out what changed – ideally the API can make it easy to check for and see changes.


#18

Hi, that is great news, really looking forward to this.

Dynalist is very flexible and can be the hub that feeds different representations of the same data: Calendar (2-way sync pending :slight_smile: ), kanban board (e.g. Trello).

To allow us enthousiasts to create an ecosystem of addons, you need to expose a generic API.

e.g. I would enjoy developing a process that does bulk rescheduling of tasks with dates, using durations and priorities (colors and nesting). I could use a notation that means duration for its users (e.g. dur:[30m]) even if it is plain text for dynalist.
Or time-tracking/pomodoro apps can integrate to grad a “today’s tasks fed from a search”.

My suggestions on the actual API:

  • Represent documents and search results as nested json of items. Todoist API represents tasks a flat array of items with indentation as number, please don’t go that way it is so awkward!

  • Define convention of the default place in the text to add date and tags, so that APIs can directly add/edit tags and date. This way you own the convention and its UX implications rather than having every API dev do its own thing.

  • Expose the GUID of each item to allow for effortless update/deletes of items. You own the identity tracking, not the API dev. The main limitation for tools like IFTTT etc is that they don’t have a 2-way communication with the app. As a user/contributor, a good reason for developing on an API is thir richer interaction, so I would promote this kind of thing.

  • Maybe expose metadata of the item: List of tags, list of dates, links etc instead of having to parse them from the raw markdown.

In the broader spirit of 3rd party development, Trello has many addons, both inside the app (and now you pay to use them :wink: ) and as 3rd party Chrome addons. You may want to start thinking/catering for UI mods sometime in the future.

Just out of curiosity, what is your tech-stack on the back end?


#19

So a couple of things I can see as things to consider…

  • Shared documents vs My private ones.
    • If a document has sharing for read or editing, then the API shouldn’t require OAuth for those types of requests
    • However it is not a shared document at all it should have a different type of authorization to access any API for them as I think it should be important for users to understand if they’re logging in and sharing OAuth access that means the app/program can access ANY of their data not just shared documents they might have access to.
    • Would having a new type of sharing permissions, to indicate API only be worth while to end-users?
  • API throttling? Is there a limit you’ll want to have to number of requests that can be made. For instance at the moment I understand you send a number of save requests while someone is typing for example to keep the save as current as possible. Will you want to open that many requests up to APIs or throttle it back to a certain number per hour/day?

#20

I thought of another simple part of the data structure that would be great to have: for each node, besides just getting the “text”, can we also get the “public_url” which displays that text as root?

The purpose is so that if I were to create a Trello board representation of a document I have, I could add links on the Trello cards that would bring a viewer back to the corresponding Dynalist node.

Thanks!
David