News

News are announcements for employees.

News can be restricted by units and user types.

Get News

curl "https://example.ziik.io/api/news"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
  "hits": [
    {
            "id": 1201,
            "content_type": "news",
            "permissions": {
                "edit": true,
                "delete": true
            },
            "title": "This is a test news",
            "category": {
                "id": 131,
                "name": "Organisation",
                "url": "api/news/categories/131"
            },
            "files": [],
            "confirm": {
                "enabled": false
            },
            "confirm_total": 3,
            "likes": 3,
            "reads": 2,
            "comments": 5,
            "user_stats": {
              "liked": true,
              "bookmarked": false,
              "read": false,
              "seen": false
            },
            "date": 1465464791,
            "updated_at": 1465464791,
            "author": {
                "See User Service..."
            },
            "allow_comments": true,
            "latest_comment": {
                "See comments..."
            },
            "body": "This is a small news item",
            "publish": null,
            "unpublish": null,
            "uploading_files": 0,
            "userTypes": [
              {
                  "id": 345,
                  "name": "Example User Type",
                  "url": "api/usertypes/345"
              },
              {
                  "id": 456,
                  "name": "Other User Type",
                  "url": "api/usertypes/456"
              }
            ],
            "units": [
              {
                  "content_type": "unit",
                  "id": 567,
                  "name": "Example unit",
                  "url": "api/units/567"
              }
            ],
            "url": "api/news/1201"
        }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoint retrieves a list of news.

HTTP Request

GET https://example.ziik.io/api/news

Query Parameters

ParameterTypeDefaultDescription
categoryIntegerNULLIf set, only show news from this category
filterStringNULLIf set to "confirm" only shows news with confirm read enabled. If set to "bookmark" only shows news that the current user has bookmarked.
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Get Single News

curl "https://example.ziik.io/api/news/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
      "id": 1203,
      "content_type": "news",
      "permissions": {
          "edit": true,
          "delete": true
      },
      "title": "Some News #1",
      "category": {
          "id": 131,
          "name": "Organisation",
          "url": "api/news/categories/131"
      },
      "files": [],
      "confirm": {
          "enabled": false
      },
      "confirm_total": 3,
      "likes": 3,
      "reads": 2,
      "comments": 5,
      "user_stats": {
        "liked": true,
        "bookmarked": false,
        "read": false,
        "seen": false
      },
      "date": 1465464791,
      "updated_at": 1465464791,
      "author": {
          "See User Service..."
      },
      "allow_comments": true,
      "latest_comment": {
          "See comments..."
      },
      "body": "This is the news text for this news",
      "publish": 1465827551,
      "unpublish": 1465933551,
      "uploading_files": 0,
      "userTypes": [
          {
              "id": 345,
              "name": "Example User Type",
              "url": "api/usertypes/345"
          },
          {
              "id": 456,
              "name": "Other User Type",
              "url": "api/usertypes/456"
          }
      ],
      "units": [
          {
              "content_type": "unit",
              "id": 567,
              "name": "Example unit",
              "url": "api/units/567"
          }
      ],
      "url": "api/news/1203"
  }

This endpoint returns a single news story

HTTP Request

GET https://example.ziik.io/api/news/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news story

Permissions Required

  • User's unit within the news story's units
  • User's user type within the news story's user types

Create News

curl -i -X POST "https://example.ziik.io/api/news"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created news story

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/news/1234
{
    "message": "News created"
}

This endpoint creates a news story.

HTTP Request

POST https://example.ziik.io/api/news

Request Parameters

ParameterTypeRequiredDescription
titleStringYesTitle for the news story.
bodyStringNoBody text for the news story.
categoryIntegerNoID of the news category, this story belongs to
userTypesArrayNoUser type IDs of the user types, who can read this
unitsArrayNoUnits this news story should be published in
confirm_readBooleanNoIf true, news is marked as requiring read confirmation from readers
commentsBooleanNoIf true, news is open for comments
statusBooleanNoIf true, news is published, otherwise it is a draft
publishIntegerNoTimestamp for news publishing time
unpublishIntegerNoTimestamp for when the news should be unpublished
fileCountIntegerNoNumber of files that will be uploaded (type 'upload') in total, including subsequent POSTs to /api/news/ID/files
fileArrayNoFile data for an image or video to accompany the news story. If provided, must have the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Write permission to news

Edit News

curl -i -X PATCH "https://example.ziik.io/api/news/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing news story.

HTTP Request

PATCH https://example.ziik.io/api/news/ID

Request Parameters

ParameterTypeRequiredDescription
titleStringYesTitle for the news story.
bodyStringNoBody text for the news story.
categoryIntegerNoID of the news category, this story belongs to
userTypesArrayNoUser type IDs of the user types, who can read this
unitsArrayNoUnits this news story should be published in
confirm_readBooleanNoIf true, news is marked as requiring read confirmation from readers
commentsBooleanNoIf true, news is open for comments
statusBooleanNoIf true, news is published, otherwise it is a draft
publishIntegerNoTimestamp for news publishing time
unpublishIntegerNoTimestamp for when the news should be unpublished
fileArrayNoFile data for an image or video to accompany the news story. If set, replaces any existing file and must have the following values or be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Publish permission to news
  • Requesting user in the same unit as the news story's author

Delete News

curl -i -X DELETE "https://example.ziik.io/api/news/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a news story.

HTTP Request

DELETE https://example.ziik.io/api/news/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news story to delete

Permissions Required

  • Administer permission to news
  • Requesting user in the same unit as the news story's author

Get News Readers

curl "https://example.ziik.io/api/news/123/reads"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  [{
    "timestamp": 1465823551,
    "user": { "See User Service..." }
  },
  {
    "timestamp": 1465823556,
    "user": { "See User Service..." }
  },
  {
    "timestamp": null,
    "user": { "See User Service..." }
  }]

This endpoint returns a list of users, who should confirm that they have read a news story along with the timestamp of the read.

If timestamp is null, it means that they SHOULD confirm, but have not yet done so.

HTTP Request

GET https://example.ziik.io/api/news/ID/reads

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news story

Permissions Required

  • Publish permission to news
  • Requesting user in the same unit as the news story's author

Confirm Read News

curl -i -X POST "https://example.ziik.io/api/news/123/reads"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint marks a news story as confirmed read by the user.

Confirmed reads are used to make users acknowledge that they have read an announcement.

HTTP Request

POST https://example.ziik.io/api/news/123/reads

Request Parameters

None

Permissions Required

  • Read access to the news (See "Get Single News")

Get News Bookmarkers

curl "https://example.ziik.io/api/news/123/bookmarks"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  [{
    "timestamp": 1465823551,
    "user": { "See User Service..." }
  },
  {
    "timestamp": 1465823556,
    "user": { "See User Service..." }
  }]

This endpoint returns a list of users, who have bookmarked a news story along with the timestamp of the action.

HTTP Request

GET https://example.ziik.io/api/news/ID/bookmarks

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news story

Permissions Required

  • Publish permission to news
  • Requesting user in the same unit as the news story's author

Bookmark News

curl -i -X POST "https://example.ziik.io/api/news/123/bookmarks"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint bookmarks a news story for the current user.

HTTP Request

POST https://example.ziik.io/api/news/123/bookmarks

Request Parameters

ParameterTypeRequiredDescription
actionStringNo"bookmark" or "remove" on whether to add the bookmark or remove it. Defaults to "bookmark"

Permissions Required

  • Read access to the news (See "Get Single News")

Remove Bookmark on News

Use "Bookmark News" request with the request parameter "action" and value "remove"

Get News Viewers

curl "https://example.ziik.io/api/news/123/seen"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  [{
    "timestamp": 1465823551,
    "user": { "See User Service..." }
  },
  {
    "timestamp": 1465823556,
    "user": { "See User Service..." }
  }]

This endpoint returns a list of users, who have accessed a news story.

HTTP Request

GET https://example.ziik.io/api/news/ID/seen

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news story

Permissions Required

  • Publish permission to news
  • Requesting user in the same unit as the news story's author

Like News

curl -i -X POST "https://example.ziik.io/api/news/123/likes"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint marks a news story as liked by the current user.

HTTP Request

POST https://example.ziik.io/api/news/123/likes

Request Parameters

ParameterTypeRequiredDescription
actionStringNo"like" or "unlike" on whether to add the like or remove it. Defaults to "like"

Permissions Required

  • Read access to the news (See "Get Single News")

Remove Bookmark on News

Use "Like News" request with the request parameter "action" and value "remove"

Get News Likers

curl "https://example.ziik.io/api/news/123/likes"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  [{
    "timestamp": 1465823551,
    "user": { "See User Service..." }
  },
  {
    "timestamp": 1465823556,
    "user": { "See User Service..." }
  }]

This endpoint returns a list of users, who have liked a news story.

HTTP Request

GET https://example.ziik.io/api/news/ID/likes

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news story

Permissions Required

  • Publish permission to news
  • Requesting user in the same unit as the news story's author

Mark News as Seen

curl -i -X POST "https://example.ziik.io/api/news/123/seen"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint marks a news story as seen for the current user.

The difference between "seen" and "read" is that "seen" just means accessed, while "read" means a confirmation of reading (and understanding) the message of the news story.

HTTP Request

POST https://example.ziik.io/api/news/123/seen

Request Parameters

None

Permissions Required

  • Read access to the news (See "Get Single News")

Get News Categories

curl "https://example.ziik.io/api/news/categories"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  [{
      "id": "137",
      "name": "Development"
  }, {
      "id": "136",
      "name": "Events"
  }, {
      "id": "139",
      "name": "Financial"
  }, {
      "id": "164",
      "name": "Manual"
  }, {
      "id": "131",
      "name": "Organisation"
  }, {
      "id": "138",
      "name": "Partners"
  }, {
      "id": "132",
      "name": "Sales"
  }]

This endpoint returns a list of categories to use in news.

HTTP Request

GET https://example.ziik.io/api/news/categories

Get Single News Category

curl "https://example.ziik.io/api/news/categories/137"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
      "id": "137",
      "name": "Development"
  }

This endpoint returns a single news category.

HTTP Request

GET https://example.ziik.io/api/news/categories/ID

Create News Category

curl -i -X POST "https://example.ziik.io/api/news/categories"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the new category

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/news/categories/140
{
    "message": "Category created"
}

This endpoint creates a new category to be used in news.

HTTP Request

POST https://example.ziik.io/api/news/categories

Request Parameters

ParameterTypeRequiredDescription
nameStringYesName of the new category.

Permissions Required

  • Administer permission to news

Edit News Category

curl -i -X PATCH "https://example.ziik.io/api/news/categories/140"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing news category.

HTTP Request

PATCH https://example.ziik.io/api/news/categories/ID

Request Parameters

ParameterTypeRequiredDescription
nameStringYesNew name for the category.

Permissions Required

  • Administer permission to news

Delete News Category

curl -i -X DELETE "https://example.ziik.io/api/news/categories/140"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a news category.

HTTP Request

DELETE https://example.ziik.io/api/news/categories/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news category to delete

Permissions Required

  • Administer permission to news

Add Files To News

curl -i -X POST "https://example.ziik.io/api/news/files"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint adds files to an existing news story.

HTTP Request

POST https://example.ziik.io/api/news/files

Request Parameters

ParameterTypeDescription
idIntegerThe ID of the news to add files to
filesArrayNo
- typeStringYes
- nameStringYes
- dataStringYes

Permissions Required

  • News edit access

Delete File From News

curl -i -X DELETE "https://example.ziik.io/api/news/124/files/12345"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a file from a news story.

HTTP Request

DELETE https://example.ziik.io/api/news/<NewsID>/files/<FileID>

URL Parameters

ParameterTypeDescription
NewsIDIntegerThe ID of the news
FileIDIntegerThe ID of the file to delete

Permissions Required

  • News edit access

Get Comments for a News

curl "https://example.ziik.io/api/news/124/comments"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  [{
      "id":1241,
      "author":{
          "id":234,
          "name":"Test User",
          "avatar":{
              "id":"345",
              "name":"avatar.png",
              "mime":"image/png",
              "size":"54314",
              "type":"image",
              "source":"https://example.ziik.io/api/file/default_images/avatar.png",
              "versions":{
                  "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
                  "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
                  "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
              }
          },
          "userType":{
              "id":11,
              "name":"Worker",
              "url":"api/user_types/11"
          },
          "url":"api/users/234"
      },
      "body": "This is a comment",
      "files": [{
          "id":"345",
          "name":"filename.png",
          "mime":"image/png",
          "size":"54314",
          "type":"image",
          "source":"https://example.ziik.io/api/file/groups/avatar.png",
          "versions":{
              "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
              "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
              "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
          }
      }],
      "date":1465910290,
      "url":"api/comments/1241"
    },
    {
      "id":1242,
      "author":{
          "id":234,
          "name":"Test User",
          "avatar":{
              "id":"345",
              "name":"avatar.png",
              "mime":"image/png",
              "size":"54314",
              "type":"image",
              "source":"https://example.ziik.io/api/file/default_images/avatar.png",
              "versions":{
                  "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
                  "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
                  "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
              }
          },
          "userType":{
              "id":11,
              "name":"Worker",
              "url":"api/user_types/11"
          },
          "url":"api/users/234"
      },
      "body": "This is another comment",
      "files": [{
          "id":"345",
          "name":"filename.png",
          "mime":"image/png",
          "size":"54314",
          "type":"image",
          "source":"https://example.ziik.io/api/file/groups/avatar.png",
          "versions":{
              "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
              "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
              "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
          }
      }],
      "date":1465910290,
      "url":"api/comments/1242"
    }]

This endpoint returns all comments for a news

HTTP Request

GET https://example.ziik.io/api/news/ID/comments

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the news story

Permissions Required

  • Access to the news story

Create New Comment

curl -i -X POST "https://example.ziik.io/api/news/124/comments"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the new comment

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/comments/1234
{
    "message": "Comment created"
}

This endpoint creates a new comment to a news.

HTTP Request

POST https://example.ziik.io/api/news/ID/comments

Request Parameters

ParameterTypeRequiredDescription
commentStringYesComment body.
fileCountIntegerNoNumber of files that will be uploaded (type 'upload') in total, including subsequent POSTs to /api/comments/ID/files
filesArrayNoFile data for files to accompany the comment. If provided, existing files are cleared. Must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Access to the news story
  • Comments enabled for the news story