Accessing Organization Metadata¶

Collectively, the set of users, components, milestones, priorities, classifications, and states are referred to as the metadata for an organization. See here for an overview of these concepts.

The Ship API provides endpoints for each type of metadata:

/api/20151105/users
/api/20151105/components
/api/20151105/milestones
/api/20151105/priorities
/api/20151105/classifications
/api/20151105/states

A /search endpoint is available taking a predicate parameter for each of the above (e.g. /api/20151105/users/search?predicate=...). The predicate is in NSPredicate format. Refer to the schema for the set of available properties to search on.

Example: Accessing User Information

curl:

curl -G \
    --header "Authorization: $SHIP_API_TOKEN" \
    https://api.realartists.com/api/20151105/users

python:

api.users()

Example: Listing Active Milestones

curl:

curl -G \
    --header "Authorization: $SHIP_API_TOKEN" \
    --data-urlencode "predicate=(StartDate = nil || StartDate < NOW()) && (EndDate = nil || EndDate > NOW())" \
    https://api.realartists.com/api/20151105/milestones/search

python:

api.milestones_active()

The Python API also provides a number of metadata conveniences:

Api.me()¶: Return the user represented by the active API token.

Api.users_active()¶: Returns the list of users that have accounts in good standing with the organization (that is, they have not left the organization and have not been marked as inactive by an admin).

Api.users(predicate=None)¶: Return the list of users, optionally filtered by a predicate.

Api.components(predicate=None)¶: Return the list of components, optionally filtered by a predicate.

Api.component_parent(component)¶: Returns the component that is the parent of the passed in component.

Api.component_children(component)¶: Returns the immediate child components of the passed in component

Api.classifications()¶: Returns the list of allowed problem classifications

Api.milestones(predicate=None)¶: Return the list of all milestones, optionally filtered by a predicate

Api.milestones_active(within_component=None)¶: Returns only the milestones that are currently active (that is, those that either omit the start and end dates, or those with start and end dates where start < now < end).

Api.priorities()¶: Returns the list of priorities

Api.states(predicate=None)¶: Returns the list of states

Api.state_initial()¶: Returns the first start state

Api.states_initial()¶: Returns the list of all start states

Api.state_transitions(state)¶: Return the list of valid state transitions from state.