Searching Problems

Endpoint: /api/20151105/problems/search

Problems may be searched using the NSPredicate query language. NSPredicate queries on the Ship database schema are concise and readable yet quite powerful.

Additionally, you can execute any saved query made within the Ship app by referring to its URL.

Quick Example

curl:

curl -G \
    --header "Authorization: $SHIP_API_TOKEN" \
    --data-urlencode "predicate=watching = YES" \
    https://api.realartists.com/api/20151105/problems/search

python:

api.problem_search("watching = YES")

Additional Examples

The built in queries from the Ship app are expressed in NSPredicate syntax below:

Unread Problems Assigned to Me:

read = NO AND state.resolved = NO AND assignee.identifier = $ApiUser

Unread Problems I’m Watching:

watching = YES AND read = NO

Recently Created:

creationDate > FUNCTION(NOW(), 'dateByAddingDays:', -7)

Recently Created by Me:

originator.identifier = $ApiUser AND creationDate > FUNCTION(NOW(), 'dateByAddingDays:', -7)

Recently Modified:

modificationDate > FUNCTION(NOW(), 'dateByAddingDays:', -7)

Recently Modified By Me:

SUBQUERY(history, $h, $h.modificationDate > FUNCTION(NOW(), 'dateByAddingDays:', -7) AND $h.modifier.identifier = $ApiUser).@count > 0

My Open Problems:

assignee.identifier = $ApiUser AND state.resolved = NO

All Problems:

TRUEPREDICATE

All Open Problems:

state.resolved = NO

Additionally, the search box in the Ship app overview window works by adding an additional AND predicate term to the selected predicate like so:

title CONTAINS[c] 'API'

Or you can do just a prefix search

title BEGINSWITH[c] 'TLF'

Built-in Variables

$ApiUser - The user identifier corresponding to the provided Ship API Token.

Additional Functions

In addition to the standard NSExpression functions, the Ship API implementation provides a handful of additional functions for dealing with dates.

  • dateByAddingSeconds:
  • dateByAddingMinutes:
  • dateByAddingHours:
  • dateByAddingDays:
  • dateByAddingMonths:
  • dateByAddingYears:

Example usage is shown above.

Executing Saved Queries

To execute an existing saved query, first select the query in the Overview within the Ship app, under the sections My Queries, Recent Queries, or Bookmarked Queries. Now, Choose Edit → Copy URL (⌘⇧C), or right click and choose Copy URL.

You will now have a URL on your clipboard that looks like this:

ship://Query/UYnF8JlyQp2IQrqTBiCP7A <Document Me>

To run the query via the API, do this (but replace the example query with the one you copied):

curl:

curl -G \
    --header "Authorization: $SHIP_API_TOKEN" \
    --data-urlencode "savedQuery=ship://Query/UYnF8JlyQp2IQrqTBiCP7A <Document Me>" \
    https://api.realartists.com/api/20151105/problems/search

python:

api.problem_search(savedQueryURL="ship://Query/UYnF8JlyQp2IQrqTBiCP7A <Document Me>")