Issues API

[vaclavHala]

Issues API allows new issues to be created (reported by logged in users).
It also allows issues to be searched for and filtered. What filters do we want/need? Ideas:

• Search by location (all issues in given geo rectangle)
• Search by priority
• Search by category
• Search by author
• Show all, paged? (return at most N issues at a time, request contains offset of first issue to return)

Do we want combination of above filters to be possible?

[radike]

Multifilter would be awesome, but for simplicity, a simple filter could be used.

[vaclavHala]

I have two levels of granularity returned from issueAPI: brief and detailed.

• Brief: for showing issues on the map, only coordinates and subject (name) of the issue are returned.
  A lot of these (100s possibly) will be returned at one time.
• Detailed: for showing issue detail when user selects one concrete issue, all available info is included (category, priority, status...). Only exception is image (if any) associated with the issue. As this will be binary file it has to be retrieved separately (i.e. Presentation layer #15/image). JSON and binary data are not friends :(

Makes sense?

[radike]

+1
I think that it is a very good design.

[vaclavHala]

Issues can be filtered using composite filter.
The filter is passed as query string filter=.

Example of filter (prettyprinted here for brevity):

[
    {"@type":"category","in":["ADD","REMOVE"]},
    {"@type":"priority","min":"CAN_HAVE","max":"MUST_HAVE"},
    {"@type":"spatial","lat_min":3,"lat_max":6,"lon_min":4,"lon_max":7}
]

When sending the filter, note that it must be URL encoded (for quick manual encode/decode use this tool or any of the thousand similar ones)

The filter above will be encoded as:

%5B%7B%22%40type%22%3A%22category%22%2C%22in%22%3A%5B%22ADD%22%2C%22REMOVE%22%5D%7D%2C%7B%22%40type%22%3A%22priority%22%2C%22min%22%3A%22CAN_HAVE%22%2C%22max%22%3A%22MUST_HAVE%22%7D%2C%7B%22%40type%22%3A%22spatial%22%2C%22lat_min%22%3A3%2C%22lat_max%22%3A6%2C%22lon_min%22%3A4%2C%22lon_max%22%3A7%7D%0A%5D

Full API call with the filter for reference:

http://localhost:8080/tracker/rest/issue?filter=%5B%7B%22%40type%22%3A%22category%22%2C%22in%22%3A%5B%22ADD%22%2C%22REMOVE%22%5D%7D%2C%7B%22%40type%22%3A%22priority%22%2C%22min%22%3A%22CAN_HAVE%22%2C%22max%22%3A%22MUST_HAVE%22%7D%2C%7B%22%40type%22%3A%22spatial%22%2C%22lat_min%22%3A3%2C%22lat_max%22%3A6%2C%22lon_min%22%3A4%2C%22lon_max%22%3A7%7D%0A%5D

The result is a JSON array of simple issue details:

{
  "id": 923,
  "subject": "aliquip",
  "coords": {
    "lat": 4.769,
    "lon": 6.5056
  }
}

[vaclavHala]

Issue Workflow

To update status of issue, POST to:
http://localhost:8080/tracker/rest/issue/<ID, e.g. 2>
with body containing the new status:

{
  "status" : <status enum, e.g. "ACCEPTED">
}

This operation is only allowed for users in role 'WORKER' (has to be assigned via Redmine admin UI)

• 204 signifies the status has been updated
• 401 caller is not in role WORKER
• 403 illegal state transition (see chart above)
• 404 issue with such ID does not exist

[vaclavHala]

Added LocalDate based filter. It selects all issues created between two dates (no time), both inclusive.
The filter can be used like:

[{"@type":"date","from":"2016-05-20","to":"2016-05-30"}]

Note that the date is in ISO format, year first, then month, day last.