API: News

News are articles written by users in order to inform other users of important information.

Actions

Link Description Condition
delete Delete the new Permission: manage news
updateImmediately Directly perform edits on the news Permission: manage news

Linked Properties

Link Description Type Constraints Supported operations Condition
self This news News not null READ
project The project the news is situated in Project not null READ / WRITE
author The user having created the news User not null READ

Local Properties

Property Description Type Constraints Supported operations Condition
id News’ id Integer x > 0 READ
title The headline of the news String max 60 characters READ
summary A short summary String max 255 characters READ  
description The main body of the news with all the details String READ
createdAt The time the news was created at DateTime READ  

Methods

List news

Lists news. The news returned depend on the provided parameters and also on the requesting user’s permissions.

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:

  • id: Sort by primary key

  • created_at: Sort by news creation datetime

Example:
[["created_at", "asc"]]

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • project_id: Filter news by project

Example:
[{ "project_id": { "operator": "=", "values": ["1", "2"] } }]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "author": {
            "href": "/api/v3/users/2",
            "title": "Peggie Feeney"
          },
          "project": {
            "href": "/api/v3/projects/1",
            "title": "Seeded Project"
          },
          "self": {
            "href": "/api/v3/news/1",
            "title": "asperiores possimus nam doloribus ab"
          }
        },
        "_type": "News",
        "createdAt": "2015-03-20T12:57:01.209Z",
        "description": {
          "format": "markdown",
          "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>",
          "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui."
        },
        "id": 1,
        "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
        "title": "asperiores possimus nam doloribus ab"
      },
      {
        "_links": {
          "author": {
            "href": "/api/v3/users/2",
            "title": "Peggie Feeney"
          },
          "project": {
            "href": "/api/v3/projects/1",
            "title": "Seeded Project"
          },
          "self": {
            "href": "/api/v3/news/2",
            "title": "terminatio tutamen. Officia adeptio sp"
          }
        },
        "_type": "News",
        "createdAt": "2015-03-20T12:57:01.262Z",
        "description": {
          "format": "markdown",
          "html": "<p>Amicitia alius cattus voluntarius. Virgo viduo terminatio tutamen. Officia adeptio spectaculum atavus nisi cum concido bis. Harum caecus auxilium sol theatrum eaque consequatur. Omnis aeger suus adipisci cicuta. Cur delicate alias curto cursim atqui talio fugiat.</p>",
          "raw": "Amicitia alius cattus voluntarius. Virgo viduo terminatio tutamen. Officia adeptio spectaculum atavus nisi cum concido bis. Harum caecus auxilium sol theatrum eaque consequatur. Omnis aeger suus adipisci cicuta. Cur delicate alias curto cursim atqui talio fugiat."
        },
        "id": 2,
        "summary": "Consequatur sequi surculus creo tui aequitas.",
        "title": "terminatio tutamen. Officia adeptio sp"
      }
    ]
  },
  "_links": {
    "changeSize": {
      "href": "/api/v3/news?offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "jumpTo": {
      "href": "/api/v3/news?offset=%7Boffset%7D&pageSize=2",
      "templated": true
    },
    "nextByOffset": {
      "href": "/api/v3/news?offset=2&pageSize=2"
    },
    "self": {
      "href": "/api/v3/news?offset=1&pageSize=2"
    }
  },
  "_type": "Collection",
  "count": 2,
  "offset": 1,
  "pageSize": 2,
  "total": 78
}
List_of_NewsModel
{
  "type": "object",
  "example": {
    "_type": "Collection",
    "total": 78,
    "count": 2,
    "pageSize": 2,
    "offset": 1,
    "_embedded": {
      "elements": [
        {
          "_type": "News",
          "id": 1,
          "title": "asperiores possimus nam doloribus ab",
          "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
          "description": {
            "format": "markdown",
            "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
            "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
          },
          "createdAt": "2015-03-20T12:57:01.509Z",
          "_links": {
            "self": {
              "href": "/api/v3/news/1",
              "title": "asperiores possimus nam doloribus ab"
            },
            "project": {
              "href": "/api/v3/projects/1",
              "title": "Seeded Project"
            },
            "author": {
              "href": "/api/v3/users/2",
              "title": "Peggie Feeney"
            },
            "updateImmediately": {
              "href": "api/v3/news/1",
              "method": "patch"
            },
            "delete": {
              "href": "api/v3/news/1",
              "method": "delete"
            }
          }
        },
        {
          "_type": "News",
          "id": 2,
          "title": "terminatio tutamen. Officia adeptio sp",
          "summary": "Consequatur sequi surculus creo tui aequitas.",
          "description": {
            "format": "markdown",
            "raw": "Amicitia alius cattus voluntarius. Virgo viduo terminatio tutamen. Officia adeptio spectaculum atavus nisi cum concido bis. Harum caecus auxilium sol theatrum eaque consequatur. Omnis aeger suus adipisci cicuta. Cur delicate alias curto cursim atqui talio fugiat.",
            "html": "<p>Amicitia alius cattus voluntarius. Virgo viduo terminatio tutamen. Officia adeptio spectaculum atavus nisi cum concido bis. Harum caecus auxilium sol theatrum eaque consequatur. Omnis aeger suus adipisci cicuta. Cur delicate alias curto cursim atqui talio fugiat.</p>"
          },
          "createdAt": "2015-03-20T12:57:01.509Z",
          "_links": {
            "self": {
              "href": "/api/v3/news/2",
              "title": "terminatio tutamen. Officia adeptio sp"
            },
            "project": {
              "href": "/api/v3/projects/1",
              "title": "Seeded Project"
            },
            "author": {
              "href": "/api/v3/users/2",
              "title": "Peggie Feeney"
            },
            "updateImmediately": {
              "href": "api/v3/news/2",
              "method": "patch"
            },
            "delete": {
              "href": "api/v3/news/2",
              "method": "delete"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/api/v3/news?offset=1&pageSize=2"
      },
      "jumpTo": {
        "href": "/api/v3/news?offset=%7Boffset%7D&pageSize=2",
        "templated": true
      },
      "changeSize": {
        "href": "/api/v3/news?offset=1&pageSize=%7Bsize%7D",
        "templated": true
      },
      "nextByOffset": {
        "href": "/api/v3/news?offset=2&pageSize=2"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
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."
    }
  }
}

403

Returned if the client is not logged in and login is required.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to view this resource."
}
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."
    }
  }
}

Create news

Creates a news entry. Only administrators and users with “Manage news” permission in the given project are eligible. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

No parameters 
{
  "title": "asperiores possimus nam doloribus ab",
  "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
  "description": {
    "raw": "**Videlicet deserunt aequitas cognatus**. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui."
  },
  "_links": {
    "project": {
      "href": "/api/v3/projects/1"
    }
  }
}

{
  "title": {
    "type": "string",
    "description": "The headline of the news",
    "readOnly": true
  },
  "summary": {
    "type": "string",
    "description": "A short summary",
    "readOnly": true
  },
  "description": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Formattable"
      },
      {
        "description": "The main body of the news with all the details"
      }
    ]
  },
  "_links": {
    "type": "object",
    "required": [
      "project"
    ],
    "properties": {
      "project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The project the news is situated in\n\n**Resource**: Project"
          }
        ]
      }
    }
  }
}

201

Created

NewsModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "News' id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "title": {
      "type": "string",
      "description": "The headline of the news",
      "readOnly": true
    },
    "summary": {
      "type": "string",
      "description": "A short summary",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "The main body of the news with all the details",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the news was created at",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "author"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This news\n\n**Resource**: News",
              "readOnly": true
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the news is situated in\n\n**Resource**: Project"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user having created the news\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on the news\n\n**Permission** manage news"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Delete the news\n\n**Permission** manage news"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "News",
    "id": 1,
    "title": "asperiores possimus nam doloribus ab",
    "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
    "description": {
      "format": "markdown",
      "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
      "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
    },
    "createdAt": "2015-03-20T12:57:01.908Z",
    "_links": {
      "self": {
        "href": "/api/v3/news/1",
        "title": "asperiores possimus nam doloribus ab"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A project"
      },
      "author": {
        "href": "/api/v3/users/2",
        "title": "Peggie Feeney"
      },
      "updateImmediately": {
        "href": "api/v3/news/1",
        "method": "patch"
      },
      "delete": {
        "href": "api/v3/news/1",
        "method": "delete"
      }
    },
    "_embedded": {
      "project": {
        "_type": "Project..."
      },
      "author": {
        "_type": "User..."
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
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."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator, Manage news permission in the project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to create new news."
}
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."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
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."
    }
  }
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "title"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Title can't be blank."
}
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."
    }
  }
}

View news

id
integer

required path

news id

Example:
1

200

OK

{
  "_embedded": {
    "author": {
      "_type": "User..."
    },
    "project": {
      "_type": "Project..."
    }
  },
  "_links": {
    "author": {
      "href": "/api/v3/users/2",
      "title": "Peggie Feeney"
    },
    "project": {
      "href": "/api/v3/projects/1",
      "title": "A project"
    },
    "self": {
      "href": "/api/v3/news/1",
      "title": "asperiores possimus nam doloribus ab"
    }
  },
  "_type": "News",
  "createdAt": "2015-03-20T12:57:01.601Z",
  "description": {
    "format": "markdown",
    "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>",
    "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui."
  },
  "id": 1,
  "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
  "title": "asperiores possimus nam doloribus ab"
}
NewsModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "News' id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "title": {
      "type": "string",
      "description": "The headline of the news",
      "readOnly": true
    },
    "summary": {
      "type": "string",
      "description": "A short summary",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "The main body of the news with all the details",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the news was created at",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "author"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This news\n\n**Resource**: News",
              "readOnly": true
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the news is situated in\n\n**Resource**: Project"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user having created the news\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on the news\n\n**Permission** manage news"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Delete the news\n\n**Permission** manage news"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "News",
    "id": 1,
    "title": "asperiores possimus nam doloribus ab",
    "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
    "description": {
      "format": "markdown",
      "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
      "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
    },
    "createdAt": "2015-03-20T12:57:01.908Z",
    "_links": {
      "self": {
        "href": "/api/v3/news/1",
        "title": "asperiores possimus nam doloribus ab"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A project"
      },
      "author": {
        "href": "/api/v3/users/2",
        "title": "Peggie Feeney"
      },
      "updateImmediately": {
        "href": "api/v3/news/1",
        "method": "patch"
      },
      "delete": {
        "href": "api/v3/news/1",
        "method": "delete"
      }
    },
    "_embedded": {
      "project": {
        "_type": "Project..."
      },
      "author": {
        "_type": "User..."
      }
    }
  }
}

404

Returned if the news does not exist or if the user does not have permission to view it.

Required permission being member of the project the news belongs to

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
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."
    }
  }
}

Update news

Updates the news’s writable attributes. When calling this endpoint the client provides a single object, containing the properties and links to be updated, in the body.

id
integer

required path

News id

Example:
1

{
  "title": "asperiores possimus nam doloribus ab",
  "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
  "description": {
    "raw": "**Videlicet deserunt aequitas cognatus**. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui."
  },
  "_links": {
    "project": {
      "href": "/api/v3/projects/1"
    }
  }
}

{
  "title": {
    "type": "string",
    "description": "The headline of the news",
    "readOnly": true
  },
  "summary": {
    "type": "string",
    "description": "A short summary",
    "readOnly": true
  },
  "description": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Formattable"
      },
      {
        "description": "The main body of the news with all the details"
      }
    ]
  },
  "_links": {
    "type": "object",
    "required": [
      "project"
    ],
    "properties": {
      "project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The project the news is situated in\n\n**Resource**: Project"
          }
        ]
      }
    }
  }
}

200

OK

NewsModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "News' id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "title": {
      "type": "string",
      "description": "The headline of the news",
      "readOnly": true
    },
    "summary": {
      "type": "string",
      "description": "A short summary",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "The main body of the news with all the details",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the news was created at",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "author"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This news\n\n**Resource**: News",
              "readOnly": true
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the news is situated in\n\n**Resource**: Project"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user having created the news\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on the news\n\n**Permission** manage news"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Delete the news\n\n**Permission** manage news"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "News",
    "id": 1,
    "title": "asperiores possimus nam doloribus ab",
    "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
    "description": {
      "format": "markdown",
      "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
      "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
    },
    "createdAt": "2015-03-20T12:57:01.908Z",
    "_links": {
      "self": {
        "href": "/api/v3/news/1",
        "title": "asperiores possimus nam doloribus ab"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A project"
      },
      "author": {
        "href": "/api/v3/users/2",
        "title": "Peggie Feeney"
      },
      "updateImmediately": {
        "href": "api/v3/news/1",
        "method": "patch"
      },
      "delete": {
        "href": "api/v3/news/1",
        "method": "delete"
      }
    },
    "_embedded": {
      "project": {
        "_type": "Project..."
      },
      "author": {
        "_type": "User..."
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
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."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrators, Manage news permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to update this news."
}
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."
    }
  }
}

404

Returned if the news entry does not exist or if the API user does not have the necessary permissions to update it.

Required permission: Administrators, Manage news permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified news does not exist or you do not have permission to view it."
}
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."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
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."
    }
  }
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "title"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Title can't be blank."
}
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."
    }
  }
}

Delete news

Permanently deletes the specified news entry.

id
integer

required path

News id

Example:
1

202

Returned if the news was deleted successfully.

Note that the response body is empty as of now. In future versions of the API a body might be returned, indicating the progress of deletion.

403

Returned if the client does not have sufficient permissions.

Required permission: Administrators and Manage news permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this news entry"
}
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."
    }
  }
}

404

Returned if the news does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified news 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."
    }
  }
}