# Group Versions

## Linked Properties
|  Link               | Description                              | Type          | Constraints                                                    | Supported operations |
|:-------------------:|----------------------------------------- | ------------- | -------------------------------------------------------------- | -------------------- |
| self                | This version                             | Version       | not null                                                       | READ                 |
| definingProject     | The project to which the version belongs | Project       | only present if the project is visible for the current user    | READ                 |
| availableInProjects | Projects where this version can be used  | Projects      | not null                                                       | READ                 |

## Local Properties
| Property    | Description                                   | Type        | Constraints | Supported operations |
| :---------: | --------------------------------------------- | ----------- | ----------- | -------------------- |
| id          | Version id                                    | Integer     | x > 0       | READ                 |
| name        | Version name                                  | String      | not null    | READ                 |
| description |                                               | Formattable | not null    | READ                 |
| startDate   |                                               | Date        |             | READ                 |
| endDate     |                                               | Date        |             | READ                 |
| status      | The current status of the version             | String      | not null    | READ                 |
| createdAt   | Time of creation                              | DateTime    | not null    | READ                 |
| updatedAt   | Time of the most recent change to the version | DateTime    | not null    | READ                 |

## Versions by Project [/api/v3/projects/{project_id}/versions]

+ Model
    + Body

            {
                "_links": {
                    "self": { "href": "/api/v3/projects/11/versions" }
                },
                "total": 3,
                "count": 3,
                "_type": "Collection",
                "_embedded":
                {
                    "elements": [
                        {
                            "_links": {
                                "self": { "href": "/api/v3/versions/11" },
                                "definingProject": { "href": "/api/v3/projects/11" },
                                "availableInProjects": { "href": "/api/v3/versions/11/projects" }
                            },
                            "_type": "Version",
                            "id": 11,
                            "name": "v3.0 Alpha",
                            "description": {
                                "format": "plain",
                                "raw": "This version has a description",
                                "html": "This version has a description"
                            },
                            "startDate": "2014-11-20",
                            "endDate": null,
                            "status": "Open"
                        },
                        {
                            "_links": {
                                "self": { "href": "/api/v3/versions/12" },
                                "definingProject": { "href": "/api/v3/projects/11" },
                                "availableInProjects": { "href": "/api/v3/versions/12/projects" }
                            },
                            "_type": "Version",
                            "id": 12,
                            "name": "v2.0",
                            "description": {
                                "format": "plain",
                                "raw": "",
                                "html": ""
                            },
                            "startDate": null,
                            "endDate": null,
                            "status": "Closed"
                        },
                        {
                            "_links": {
                                "self": { "href": "/api/v3/versions/10" },
                                "definingProject": { "href": "/api/v3/projects/11" },
                                "availableInProjects": { "href": "/api/v3/versions/10/projects" }
                            },
                            "_type": "Version",
                            "id": 10,
                            "name": "v1.0",
                            "description": {
                                "format": "plain",
                                "raw": "",
                                "html": ""
                            },
                            "startDate": null,
                            "endDate": null,
                            "status": "Open"
                        }
                    ]
                }
            }

## List versions available in a project [GET]

This endpoint lists the versions that are *available* in a given project.
Note that due to sharing this might be more than the versions *defined* by that project.

+ Parameters
    + project_id (required, integer, `1`) ... ID of the project whoose versions will be listed

+ Response 200 (application/hal+json)

    [Versions by Project][]

+ Response 404 (application/hal+json)

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

    **Required permission:** view work packages **or** manage versions (on given project)

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

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The specified project does not exist."
            }

## Version [/api/v3/versions/{id}]

+ Model
    + Body

            {
                "_links": {
                    "self": { "href": "/api/v3/versions/11" },
                    "definingProject": { "href": "/api/v3/projects/11" },
                    "availableInProjects": { "href": "/api/v3/versions/11/projects" }
                },
                "_type": "Version",
                "id": 11,
                "name": "v3.0 Alpha",
                "description": {
                    "format": "plain",
                    "raw": "This version has a description",
                    "html": "This version has a description"
                },
                "startDate": "2014-11-20",
                "endDate": null,
                "status": "Open"
            }

## View Version [GET]

+ Parameters
    + id (required, integer, `1`) ... version id

+ Response 200 (application/hal+json)

    [Version][]

+ Response 404 (application/hal+json)

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

    **Required permission:** view work packages **or** manage versions (any project where the version is available)

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

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The specified version does not exist."
            }