API: Revisions

Revisions are sets of updates to files in the context of repositories linked in OpenProject.

Linked Properties

Link Description Type Constraints Supported operations
self This revision Revision not null READ
project The project to which the revision belongs Project not null READ
author The user that added this revision, if the authorName was mapped to a user in OpenProject User READ
showRevision A URL to the repository view (outside APIv3) showing this revision - not null READ

Local Properties

Property Description Type Constraints Supported operations
id Revision’s id, assigned by OpenProject Integer x > 0 READ
identifier The raw SCM identifier of the revision (e.g. full SHA hash) String not null READ
formattedIdentifier The SCM identifier of the revision, formatted (e.g. shortened unambiguous SHA hash). May be identical to identifier in many cases String not null READ
authorName The name of the author that committed this revision. Note that this name is retrieved from the repository and does not identify a user in OpenProject. String not null READ
message The commit message of the revision Formattable not null READ
createdAt The time this revision was committed to the repository DateTime not null READ

Methods

View revision

id
integer

required path

Revision id

Example:
1

200

OK

{
  "_links": {
    "author": {
      "href": "/api/v3/users/1"
    },
    "project": {
      "href": "/api/v3/projects/1"
    },
    "self": {
      "href": "/api/v3/revisions/1"
    },
    "showRevision": {
      "href": "/projects/identifier/repository/revision/11f4b07"
    }
  },
  "_type": "Revision",
  "authorName": "Some Developer",
  "createdAt": "2015-07-21T13:36:59.454Z",
  "formattedIdentifier": "11f4b07",
  "id": 1,
  "identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
  "message": {
    "format": "plain",
    "html": "<p>This revision provides new features<br/><br/>An elaborate description</p>",
    "raw": "This revision provides new features\n\nAn elaborate description"
  }
}
RevisionModel
{
  "type": "object",
  "required": [
    "identifier",
    "formattedIdentifier",
    "authorName",
    "message",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Revision's id, assigned by OpenProject",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "identifier": {
      "type": "string",
      "description": "The raw SCM identifier of the revision (e.g. full SHA hash)",
      "readOnly": true
    },
    "formattedIdentifier": {
      "type": "string",
      "description": "The SCM identifier of the revision, formatted (e.g. shortened unambiguous SHA hash). May be identical to identifier in many cases",
      "readOnly": true
    },
    "authorName": {
      "type": "string",
      "description": "The name of the author that committed this revision. Note that this name is retrieved from the repository and does not identify a user in OpenProject.",
      "readOnly": true
    },
    "message": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "The commit message of the revision",
          "readOnly": true
        }
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time this revision was committed to the repository"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "showRevision"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This revision\n\n**Resource**: Revision",
              "readOnly": true
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project to which the revision belongs\n\n**Resource**: Project",
              "readOnly": true
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user that added this revision, if the authorName was mapped to a user in OpenProject\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "showRevision": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "A URL to the repository view (outside APIv3) showing this revision\n\n**Resource**: -",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Revision",
    "_links": {
      "self": {
        "href": "/api/v3/revisions/1"
      },
      "project": {
        "href": "/api/v3/projects/1"
      },
      "author": {
        "href": "/api/v3/users/1"
      },
      "showRevision": {
        "href": "/projects/identifier/repository/revision/11f4b07"
      }
    },
    "id": 1,
    "identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
    "formattedIdentifier": "11f4b07",
    "authorName": "Some Developer",
    "message": {
      "format": "plain",
      "raw": "This revision provides new features\n\nAn elaborate description",
      "html": "<p>This revision provides new features<br/><br/>An elaborate description</p>"
    },
    "createdAt": "2015-07-21T13:36:59.859Z"
  }
}

404

Returned if the revision does not exist or the client does not have sufficient permissions to see it.

Required permission: view changesets for the project the repository is created in.

Note: A client without sufficient permissions shall not be able to test for the existence of a revision. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified revision does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}