Creating and Updating Problems

Creating New Problems

Endpoint: POST /api/20151105/problems

A new problem can be created by performing a POST to the above endpoint with JSON data describing the new problem. The POST-ed data must contain a title at a minimum, but may include any additional fields from the problem schema as well.

Example:

curl:

curl \
    --header "Authorization: $SHIP_API_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{ "title" : "My 1st API Problem" }' \
    https://api.realartists.com/api/20151105/problems

python:

api.problem_create({ "title" : "My 1st Python API Problem" })

Updating Existing Problems

Endpoint: PATCH /api/20151105/problems/{identifier}

An existing problem may be updated by performing a PATCH to the above endpoint with the identifier of the problem to update. As with creating problems, the JSON encoded request body contains just the fields you wish to set on the problem. For certain types of one-to-many collection data, specialized endpoints exist for modifying or deleting entries in these collections (e.g. comments, relationships, keywords, problem watchers, …).

Example:

curl:

curl \
    --request PATCH \
    --header "Authorization: $SHIP_API_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{ "state" : { "name" : "Closed" } }' \
    https://api.realartists.com/api/20151105/problems/1

python:

api.problem_update(1, { "state" : { "name" : "Closed" } })

In the example given above, note that the state object is a just a partial description of the full state object, which normally has a number of other distinguishing fields. For the sake of brevity, the create and update problem endpoints allow you to specify only enough fields of a specific metadata object type as are necessary to disambiguate the object.

Updating One-To-Many Collections on Existing Problems

Adding Comments

Endpoint: POST /api/20151105/problems/{identifier}/comments

A plain text comment may be added by posting plain text to the endpoint shown above.

Example:

curl:

curl \
    --request POST \
    --header "Authorization: $SHIP_API_TOKEN" \
    --header "Content-Type: text/plain" \
    --data 'Hello There' \
    https://api.realartists.com/api/20151105/problems/1/comments

python:

api.problem_comments_append(1, "Hello There")

Listing Problem Keywords

The set of problem keywords are returned by the normal problems endpoint under the keywords property. See Loading Problems for more information.

Setting Problem Keywords

Endpoint: PUT /api/20151105/problems/{identifier}/keywords/{keyword}

Example: Set the keyword/value pair “Hello”=”World” on Problem #1:

curl:

curl \
    --request PATCH \
    --header "Authorization: $SHIP_API_TOKEN" \
    --header "Content-Type: application/json" \
    --data '"world"' \
    https://api.realartists.com/api/20151105/problems/1/keywords/hello

python:

api.problem_keyword_set(1, "Hello", "World")

Removing Problem Keywords

Endpoint: DELETE /api/20151105/problems/{identifier}/keywords/{keyword}

Example: Delete the keyword “hello” on Problem #1:

curl:

curl \
    --request DELETE \
    --header "Authorization: $SHIP_API_TOKEN" \
    https://api.realartists.com/api/20151105/problems/1/keywords/hello

python:

api.problem_keyword_delete(1, "hello")

Updating Problem Relationships

Endpoint: GET|PUT|DELETE /api/20151105/problems/{identifier}/relationships

A given problem may have one or more relationships with other problems. Each type of relationship has a corresponding mirrored type such that the related problem has the mirrored relationship type with the initial problem.

For example:

1 == Parent Of => 2
2 == Child Of => 1

When adding a relationship between two problems via the API (or via the client software as well), it is sufficient to specify just one side of the relationship. The server will take on the responsibility to establish the corresponding other side of the relationship.

To add a relationship, perform an HTTP PUT to the relationships endpoint for the problem you wish to modify.

For example, to add a parent relationship from problem 1 to problem 2:

curl:

curl \
    --request PUT \
    --header "Authorization: $SHIP_API_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{"type": "ParentOf", "problemIdentifier" : 2}'
    https://api.realartists.com/api/20151105/problems/1/relationships

python:

api.problem_relationship_add(1, shipapi.RelationTypeParentOf, 2)

To remove an existing relationship, perform an HTTP DELETE to the relationships endpoint for the problem you wish to modify. Note that to modify the type of an existing relationship, it is necessary to first delete the existing relationship and then add the new relationship.

For example, to delete the relationship added above:

curl:

curl \
--request DELETE \
--header "Authorization: $SHIP_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"type": "ParentOf", "problemIdentifier" : 2}'
https://api.realartists.com/api/20151105/problems/1/relationships

python:

api.problem_relationship_delete(1, { "type": shipapi.RelationTypeParentOf, problemIdentifier: 2})

Listing Problem Relationships

See Loading Problems for more information.

Adding Watchers to a Problem

Endpoint: PUT /api/20151105/problems/{identifier}/watchers

To add a user to the watch list for a problem, perform an HTTP PUT to the above endpoint, passing a JSON encoded User object as the body of the request. Note that it is not necessary to pass the full User object, merely passing a uniquely identifying slice of the object is sufficient.

For example, to add the user james@realartists.com to the watchers of Problem #1:

curl:

curl \
--request PUT \
--header "Authorization: $SHIP_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"email": "james@realartists.com"}'
https://api.realartists.com/api/20151105/problems/1/watchers

python:

api.problem_watchers_add(1, 'james@realartists.com')

Note

It is not possible to remove a user from the list of watchers via the API. Each added watcher must remove herself via the Ship client.