Page MenuHomePhabricator

more consistency between results of maniphest.query and .search
Closed, ResolvedPublic

Description

The newer, preferred, .search API is missing some fields in its return value that force a client to continue to use .query. In particular, the description, projectPHIDs are missing. Maybe it makes sense to add an attachment that includes this information?

Event Timeline

The projects attachment should let you get projects, here's an example call on this install to retrieve this task:

Screen Shot 2017-03-28 at 4.39.11 PM.png (1×2 px, 236 KB)

I believe "description" isn't currently included because the field type is technically "remarkup", and I wasn't sure if we might want to add features to let you retrieve a text/html rendered version (you can also currently render to text with remarkup.process, although this is an older API method and probably due for revision at some point, and does not provide rendering to plain text). There's also a remote possibility that we might let objects have some other markup language in some cases in the future (e.g., see T2849), although I think this is unlikely. We can future-proof both these cases easily enough, though.

What are you planning to use the "description" for?

We currently display the description in the reports we generate and those reports are themselves markdown, our tools currently upload these docs to phriction.

D17603 makes maniphest.search return a "description" field, which looks like this:

"description": {
  "raw": "..."
}

The "raw" field is the raw Remarkup value. I'm returning a dictionary so that we could some day return a result like this (with text and HTML rendering and other metadata) if we wanted, without breaking existing callers:

{
  "type": "remarkup",
  "raw": "**raw**",
  "html": "<strong>raw</strong>",
  "text": "raw"
}