revision

Use this resource to query revisions or to create revisions of a process, policy, or decision.

Method summary

HTTP Method Path Description
GET /scr/api/revision/[process|policy|decision]/{artifact_id} Retrieves a list of revisions for a process, policy, or decision. The default query retrieves only user-created revisions.
POST /scr/api/revision/[process|policy|decision]/{artifact_id} Creates a revision for the current tip of a process, policy, or decision.

GET /scr/api/revision/[process|policy|decision]/{artifact_id}

Description
Use this method to retrieve a list of revisions for a process, policy, or decision.
Resource information
Requirements Description
Response format JSON
Requires authentication Yes. The user must be an editor for the process, policy, or decision.
Supports OAuth 2 client credentials Yes using a User Service ID containing Artifact Reporting Category
Rate limited No
Parameters
Name Location Description Required Type
X-On-Behalf-Of Header The user context. The value must be a username in the account. The user must have permission to perform the action in the account and in the specified parent space, if any. Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential. String
artifact_id Path The ID of the artifact for which the revisions are returned. Yes String
showAll Query If this parameter is set to true, all revisions (including system-created revisions) for a process or decision are returned. Otherwise, only user-created revisions are returned. The default value is false. No Boolean
Response
Example 1 input
Get all user-created revisions for a process with the ID 130024:
  • Using User Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token" 
    "https://your_server_url/scr/api/revision/process/130024"
  • Using Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token 
 "https://your_server_url/scr/api/revision/process/130024"
  • Using Service ID OAuth 2 client credentials with user context:
    curl -i -H "Authorization: Bearer access_token" -H "X-On-Behalf-Of:user_name@domain.com" 
    "https://your_server_url/scr/api/revision/process/130024"
Example 1 output

Get all user-created revisions for a process with the ID 130024: 

 HTTP/1.1 200 OK
 {
   "creationTime": "2013-01-14T07:22:03-0500",
   "id": "130024",
   "hasDiagram": "true",
   "lastModified": "2013-01-14T07:51:22-0500",
   "revisions": [
      {
         "id": "130089",
         "hasDiagram": "true",
         "label": "Second Snapshot",
         "time": "2013-01-14T07:51:22-0500",
         "revisionType": "userSnapshot"
      },
      {
         "id": "130065",
         "hasDiagram": "true",
         "label": "First Snapshot",
         "time": "2013-01-14T07:48:00-0500",
         "revisionType": "userSnapshot"
      }
   ],
   "tip": "130089"
}
Example 2 input
Get all revisions for a process with the ID 130024:
  • Using User Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token" 
    "https://your_server_url/scr/api/revision/process/130024?showAll=true"
  • Using Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token 
"https://your_server_url/scr/api/revision/process/130024?showAll=true"
  • Using Service ID OAuth 2 client credentials with user context:
    curl -i -H "Authorization: Bearer access_token" -H "X-On-Behalf-Of:user_name@domain.com" 
    "https://your_server_url/scr/api/revision/process/130024?showAll=true"
Example 2 output

Get all revisions for a process with the ID 130024: 

 HTTP/1.1 200 OK
 {
   "creationTime": "2013-01-14T07:22:03-0500",
   "id": "130024",
   "hasDiagram": "true",
   "lastModified": "2013-01-14T07:51:22-0500",
   "revisions": [
      {
         "id": "130089", 
         "hasDiagram": "true",
         "label": "Second Snapshot",
         "time": "2013-01-14T07:51:22-0500",
         "revisionType": "userSnapshot"
      },
      {
         "id": "130065", 
         "hasDiagram": "true",
         "label": "First Snapshot",
         "time": "2013-01-14T07:48:00-0500",
         "revisionType": "userSnapshot"
      },
      {
         "id": "130055",
         "hasDiagram": "false",
         "label": "Before diagram creation",
         "time": "2013-01014T07:20:22-0500",
         "revisionType": "systemSnapshot"
      },
   ],
   "tip": "130089"
}
Response properties
creationTime
The time when the process or the policy was created.
id
The ID of the process, policy, or decision. This ID is the artifact_id that is provided in the request URI. The artifact_id becomes the ID for each revision.
hasDiagram
Whether the process has a diagram. This property is valid only for processes.
lastModified
The time when the process, policy, or decision was last modified.
revisions
The list of revisions of the process, policy, or decision. This list is organized in reverse chronological order.
revisions.hasDiagram
Whether the revision has a diagram. This property is valid only for processes.
revisions.id
The ID of the revision.
revisions.label
The label that was given to the revision when a snapshot or revision was created.
revisions.revisionType
The type of revision, either userSnapshot or systemSnapshot.
revisions.time
The time when the revision was created.
tip
The current tip of the process. It determines whether the latest revision is the same as the tip; in the previous example output, they are the same.
Response messages
HTTP code Reason
200 with JSON payload

The request was completed successfully.
400 The URI syntax is incorrect, or the artifact with the provided ID does not exist.
401

The user isn't authorized to make the request.
403
Access is forbidden. This message might appear for one of the following reasons:
  • The specified credentials are invalid.
  • This user isn't an editor for this process.
  • APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab.
  • The administrator didn't accept the Terms and Conditions of service.

POST /scr/api/revision/[process|policy|decision]/{artifact_id}

Description
Use this method to create a new revision for the current tip of a process, policy, or decision.
Resource information
Requirements Description
Response format JSON
Requires authentication Yes. The user must be an editor for the process, policy, or decision.
Supports OAuth 2 client credentials Yes using a User Service ID containing Artifact Reporting Category
Rate limited No
Parameters
Name Location Description Required Type
X-IBM-API-Version Header The requested API version is 20160630. Yes String
X-On-Behalf-Of Header The user context. The value must be a username in the account. The user must have permission to create a snapshot in the account for the artifact that is defined by the artifact_id parameter. Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential. String
artifact_id Path The ID of the artifact for which the revisions are returned. Yes String
label Query This label for the revision must be URI-encoded. Yes String
Response
Example input
Create a revision for the tip of process 130054 named Third Snapshot:
  • Using User Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token" -H "X-IBM-API-Version:20160630" 
    -X POST "https://your_server_url/scr/api/revision/process/130054?label=Third%20Snapshot"
  • Using Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token" -H "X-IBM-API-Version:20160630" 
    -X POST "https://your_server_url/scr/api/revision/process/130054?label=Third%20Snapshot"
  • Using Service ID OAuth 2 client credentials with user context: 
    curl -i -H "Authorization: Bearer access_token" -H "X-IBM-API-Version:20160630" -H "X-On-Behalf-Of:user_name@domain.com" 
    -X POST "https://your_server_url/scr/api/revision/process/130054?label=Third%20Snapshot"
Example output
Create a revision for the tip of process 130054 named Third Snapshot: 
HTTP/1.1 200 OK
Content-Length: 180
{
   "id": "1300a1",
   "label": "Third Snapshot",
   "time": "2013-01-14T08:08:22-0500"
}
Response properties
id
The ID of the created revision.
label
The label of the created revision.
time
The time when the revision was created.
Response messages
HTTP code Reason
200 with JSON payload

The request was completed successfully.
400 The URI syntax is incorrect, or the artifact with the provided ID does not exist.
401

The user isn't authorized to make the request.
403
Access is forbidden. This message might appear for one of the following reasons:
  • The specified credentials are invalid.
  • This user isn't an editor for this process.
  • APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab.
  • The administrator didn't accept the Terms and Conditions of service.