New task subtypes and better type information

api

#1

Hi everyone, we’ve got an announcement to make about an upcoming product feature. Later this year, Asana will be introducing a new task type. While we unfortunately can’t provide full details around what the new task type is, we can tell you about the API implications to help your apps be resilient to the change.

This first new task type we’re releasing will be almost identical to the “normal” tasks you’re familiar with. The one exception is that these new task types cannot have start dates, even for premium users. The consequence here is that blindly setting start dates on tasks could cause errors if one of those tasks is this new subtype.

To signal information about a task’s subtype, we’re formalizing how we communicate information about types and subtypes across our entire API. There are several other places beyond tasks where information about types and subtypes is important, so we’re taking this opportunity to make a broader specification.

  • All objects will now contain a resource_type field that describes the primary type of the object. These will correspond to the resource type you’d expect from our API routes, so the results from GET /tasks will have resource_type: "task".
  • Objects that have subtypes will now contain a resource_subtype field that describes any secondary type information. This will apply to tasks, custom fields, and stories.
    • For tasks, you will see resource_subtype: "default_task" on the tasks you’re familiar with now, and the new task type will have a different, appropriately-named value for this field.
    • Custom fields will carry over the same three types you’d expect, "text", "number", and "enum".
    • Story subtypes are having some additional work done on them… we’ll talk more about that in a separate post very soon!

One question that may come to your mind is “What about the existing type field on objects?” Because this field is already in use (heavily for custom fields), it would be a painful deprecation for us to repurpose it as the primary type of the object. However, for backwards compatibility, that field will remain on objects unchanged, though it will no longer be part of the officially supported API interface.

To alleviate the issue of suddenly having tasks that cannot have start dates when your app might be expecting otherwise, we’ll be using our deprecations framework to let you suppress these errors. For the first four weeks after these new task types launch, the default API behavior will be to silently accept changes to the new tasks’ start dates without actually changing the data. For the four weeks after that, the default behavior will be to return an error. At anytime during those eight weeks, you can use the appropriate headers (e.g., Asana-Enable: new_task_subtypes) to choose which behavior you want, and after those eight weeks the behavior will permanently be to return an error.

If you have any additional questions, go ahead and ask them in this thread and we’ll respond to them with as much information as we can. We’ll also update this post as necessary to clarify or expand on some of the points.


#2