Adding tags to tasks are not working well

[kutysam]

Tag example is wrong. Correct: body = {"data": {"tag": "TAG_GUID"}}

This should be the correct one instead of Wrong: body = {"data": {"param1": "value1", "param2": "value2",}} # dict | The tag to add to the task. https://github.com/Asana/python-asana/blob/v5.0.3/docs/TasksApi.md#add_tag_for_task

Do try it out and see.

for normal api, it should be like this
https://app.asana.com/api/1.0/tasks/task_GUID/addTag
{
  "data": {
    "tag": tag_GUID
  }
}

[jv-asana]

Hi @kutysam,

The sample request body {"data": {"param1": "value1", "param2": "value2",}} is meant to be a generic place holder for POST and or PUT request bodies. It is up to the developer to look at the BODY PARAMS section of the particular endpoint's documentation to understand what values need to be passed into the request body.

This is where that sample place holder is being defined.

Ideally, the sample code for the request body should contain examples of request bodies for that particular endpoint. We are aware of this issue. This is a bit of a trickier problem to solve since we are using an open-source generator which parses our public OpenAPI Spec and stores the values into classes that the code generator can access. For POST and PUT endpoint parameters in particular, the generator does not pass in sample values for request body params so we had to put in the place holder values of {"data": {"param1": "value1", "param2": "value2",}}. We plan on changing this to {"data": {"<PARAM_1>": "<VALUE_1>", "<PARAM_2>": "<VALUE_2>",}} in our next update so that it would be more clear that these values are placeholders. In the future, we'll try to investigate a solution that would provide actual example values instead of having to rely on this placeholder.

Similar to the sample code you shared this would be how you would make that request:

import asana
from asana.rest import ApiException
from pprint import pprint

configuration = asana.Configuration()
configuration.access_token = '<YOUR_ACCESS_TOKEN>'
api_client = asana.ApiClient(configuration)

# create an instance of the API class
tasks_api_instance = asana.TasksApi(api_client)
body = {"data": {"tag": "<YOUR_TAG_GID>",}} # dict | The tag to add to the task.
task_gid = "<YOUR_TASK_GID>" # str | The task to operate on.

try:
    # Add a tag to a task
    api_response = tasks_api_instance.add_tag_for_task(body, task_gid)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling TasksApi->add_tag_for_task: %s\n" % e)

[kutysam]

Yup understood. I just found it odd to specify more params in the example when the only param that is being accepted is "tag". But I understand you guys are doing a WIP for it.

On a side note: is there any repo that i can create an issue for the documentation? They specified body params -> tag -> string. I would like to create a modification of "The tag to add to the task" to "The tag's GUID to add to the task")

[jv-asana]

Yes. Feedback for the Asana developer documentation text changes can be provided by clicking on the "Send feedback" button which links to: https://form-beta.asana.com/?k=C4sELCq6hAUsoWEY0kJwAA&d=15793206719

For a bit of context, the Asana API Reference in the Asana Developer Documentation is generated from Asana's public OpenAPI Spec located in the Asana/openapi repo.

If you search through the Asana public OpenAPI Spec for "The tag to add to the task" you can see how this description is being pulled into the description for tag request body params for the Add a tag to a task endpoint