Upgrading from v1

General changes

Almost all GET endpoints have changed in the structure of the returned data. POST endpoints now return the created object as JSON instead of just the id as plain text.

Data wrapping

Most GET requests have changed to wrap multiple elements in the 'data' key instead of 'hits' Single objects that used to not be wrapped are also wrapped in 'data'

e.g. old:

  {
      "id": 1225,
      "content_type": "faq",
      "permissions": {
          "edit": true,
          "delete": true
      },
      "question": "This is a test faq",
      "answer": "This is the answer to the test faq",
      "categories": [{
          "id": 140,
          "name": "Technical",
          "url": "api/faq/categories/140"
      }, {
          "id": 142,
          "name": "Administration",
          "url": "api/faq/categories/142"
      }],
      "userTypes": [{
          "id": 129,
          "name": "Country-Partner",
          "url": "api/usertypes/129"
      }, {
          "id": 169,
          "name": "HQ-Development",
          "url": "api/usertypes/169"
      }],
      "files": [],
      "url": "api/faq/1225"
  }

new:

{
  "data": {
    "id": 1,
    "content_type": "faq",
    "question": "Id sed quas delectus a.",
    "answer": "<p>Voluptas quia illo eligendi quisquam. Ipsa architecto est voluptate ducimus unde eum. Voluptates voluptate deleniti ipsum vel sed. Et ratione numquam neque ut eum rerum modi.</p>",
    "author": {
      "content_type": "user",
      "id": 3,
      "name": "Santa Kling",
      "first_name": "Santa",
      "last_name": "Kling",
      "title": "Radiologic Technologist and Technician",
      "avatar": null,
      "active": true,
      "unit": {
        "content_type": "unit",
        "id": 1,
        "name": "HQ",
        "level": 0,
        "unit_type": "unit",
        "url": "api/units/1"
      },
      "physicalUnit": {
        "content_type": "unit",
        "id": 1,
        "name": "HQ",
        "level": 0,
        "unit_type": "unit",
        "url": "api/units/1"
      },
      "url": "api/users/3"
    },
    "publish": {
      "published_at": 1540545319,
      "created_at": 1540545319,
      "updated_at": 1540545319
    },
    "categories": [],
    "uploading_files": 0,
    "files": [],
    "visibility": {
      "units": [
        {
          "content_type": "unit",
          "id": 1,
          "name": "HQ",
          "level": 0,
          "unit_type": "unit",
          "falldown": false,
          "url": "api/units/1"
        }
      ],
      "userTypes": [
        {
          "id": 1,
          "name": "Manager"
        },
        {
          "id": 2,
          "name": "Employee"
        }
      ]
    },
    "permissions": {
      "edit": false,
      "delete": false
    },
    "url": "api/faq/1"
  }
}

Publishing

Data denoting content publishing - such as created and edited timestamps as well as published/unpublished status and future publishing - has been collected under the 'publish' key.

Visibility

Content - such as News, Events and FAQs - visibility of units and userTypes has ben collected under the 'visibility' key.

Sharing

Content that can be shared individually - Events and Folders - have information about the sharing under the 'sharing' key.

Read Confirmation

Read confirmation now has its own 'confirm' key under which all settings regarding read confirmation reside.

Comments

Comments on content - including the latest comment - is now always under the 'comments' key. Replies are under each individual comment.

Stats

Stats are generally under the relevant key - e.g. count under comments denotes the number of comments to the content - but are also generally collected under the 'stats' key where each sub-key (comments, likes, users) is assumed to be an integer.

User Stats

The 'user_stats' key on e.g. a news item has been renamed to 'interaction' to better describe that it is about how the current user has interacted with the item.

Pagination

The structure of pagination meta data has changed:

    "meta": {
        "pagination": {
            "total": 315,
            "count": 50,
            "per_page": 50,
            "current_page": 2,
            "total_pages": 7,
            "links": []
        }
    }

to:

  "links": {
    "first": "https://example.ziik.io/api/folders/1/documents?page=1",
    "last": "https://example.ziik.io/api/folders/1/documents?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://example.ziik.io/api/folders/1/documents",
    "per_page": 50,
    "to": 5,
    "total": 5
  }

File Handling

Uploading files along with content creation in POST requests has been removed. Uploading files now require the content to be created first and files uploaded through subsequent calls to /api/TYPE/files with the ID of the content type sent as the 'id' parameter.

Single File Properties

Certain content - units and users, most notably - has only a single image and therefore now has POST endpoint to /api/units/image and DELETE endpoint to /api/units/ID/image no longer requiring the ID of the image to delete it.

Endpoints Count

There are generally more endpoints now controlling individual parts of objects.

Interaction

POST requests to delete interaction (e.g. bookmarks, likes) has been replaced with DELETE requests to the same URL as the POST request to register interaction.

Unit Addresses

Unit addresses are now independently managed through endpoints instead of having large amounts of data sent through /api/units/ID.

Naming Changes

There is now a distinction between 'permissions' and 'abilities'

Permissions

Permissions denote what the current user can do with the specific JSON object. E.g. edit a particular news or delete a particular user.

Abilities

Abilities denote an ability of a user type or user to perform general actions. E.g. approve shift trades or publish news.