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.