From cd9cc56078287656845c0bb886596d67854b6af4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikola=20Mari=C4=87?= Date: Tue, 19 Dec 2023 14:49:34 +0100 Subject: [PATCH 1/3] feat: update GET Employees attributes docs --- personio-personnel-data-api-oa3.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/personio-personnel-data-api-oa3.yaml b/personio-personnel-data-api-oa3.yaml index 3851d2c..03c7ca6 100644 --- a/personio-personnel-data-api-oa3.yaml +++ b/personio-personnel-data-api-oa3.yaml @@ -49,13 +49,13 @@ paths: - name: updated_since in: query required: false - description: "Find all employees that have been updated since the provided date. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the updated_since filter, the email, limit, and offset parameters are ignored." + description: "Find all employees that have been updated since the provided date. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the updated_since filter, the email, limit, and offset parameters are ignored. In case `attributes[]` query parameter is provided, only the employees that had one of the provided attributes updated will be returned." schema: type: string example: 2022-12-24T08:15:30 - name: attributes[] in: query - description: Define a list of whitelisted attributes that shall be returned for all employees. + description: "A list of attributes that will be returned for all employees. In case `updated_since` query parameter is used, this list will be used to filter returning only the employees that had one of the provided attributes updated since `updated_since`." required: false schema: type: array From b7aaca9388f5baaa2ff811f589b7c3007d258be9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikola=20Mari=C4=87?= Date: Wed, 20 Dec 2023 11:41:14 +0100 Subject: [PATCH 2/3] feat: clarify - filter/selection vs filter/projection --- personio-personnel-data-api-oa3.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/personio-personnel-data-api-oa3.yaml b/personio-personnel-data-api-oa3.yaml index 03c7ca6..06ccedf 100644 --- a/personio-personnel-data-api-oa3.yaml +++ b/personio-personnel-data-api-oa3.yaml @@ -49,13 +49,13 @@ paths: - name: updated_since in: query required: false - description: "Find all employees that have been updated since the provided date. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the updated_since filter, the email, limit, and offset parameters are ignored. In case `attributes[]` query parameter is provided, only the employees that had one of the provided attributes updated will be returned." + description: "Filter to select and return only the employees that have been updated after `updated_since`. When it is used together with the `attributes[]` query parameter, the filter will select only the employees that have had any of the provided `attributes[]` updated since `updated_since`. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the `updated_since` filter, the `email`, `limit`, and `offset` parameters are ignored." schema: type: string example: 2022-12-24T08:15:30 - name: attributes[] in: query - description: "A list of attributes that will be returned for all employees. In case `updated_since` query parameter is used, this list will be used to filter returning only the employees that had one of the provided attributes updated since `updated_since`." + description: "A list of attributes that will be returned for the employees, ie. a projection. In case `updated_since` query parameter is used, this list will additionally be used to filter returning only the employees that have had at least one of the provided `attributes[]` updated since `updated_since`, ie. a selection." required: false schema: type: array From 202d6dee4d3761ab7ce727e7933b443a40ef9978 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikola=20Mari=C4=87?= Date: Thu, 21 Dec 2023 14:34:03 +0100 Subject: [PATCH 3/3] feat: Add clarifying examples for GET Employees attributes[] and updated_since combinations --- personio-personnel-data-api-oa3.yaml | 151 +++++++++++++++++++++++++-- 1 file changed, 143 insertions(+), 8 deletions(-) diff --git a/personio-personnel-data-api-oa3.yaml b/personio-personnel-data-api-oa3.yaml index 06ccedf..7c53475 100644 --- a/personio-personnel-data-api-oa3.yaml +++ b/personio-personnel-data-api-oa3.yaml @@ -46,21 +46,156 @@ paths: description: "Find an employee with the given email address. The response is still a list, containing only the filtered employee. NOTE: when using the updated_since filter, the email filter is ignored." schema: type: string - - name: updated_since - in: query - required: false - description: "Filter to select and return only the employees that have been updated after `updated_since`. When it is used together with the `attributes[]` query parameter, the filter will select only the employees that have had any of the provided `attributes[]` updated since `updated_since`. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the `updated_since` filter, the `email`, `limit`, and `offset` parameters are ignored." - schema: - type: string - example: 2022-12-24T08:15:30 - name: attributes[] in: query - description: "A list of attributes that will be returned for the employees, ie. a projection. In case `updated_since` query parameter is used, this list will additionally be used to filter returning only the employees that have had at least one of the provided `attributes[]` updated since `updated_since`, ie. a selection." + description: |- + A list of attributes that will be returned for the employees, ie. a projection of the employee fields and relationships. In case `updated_since` query parameter is used, this list will additionally be used to exclude the employees that had none of the provided `attributes[]` updated since `updated_since`, ie. a selection filter. + example: "?attributes[]=first_name&attributes[]=last_name" required: false schema: type: array items: type: string + example: ["first_name", "last_name"] + - name: updated_since + in: query + required: false + description: >2- # indentation is 2 spaces (so code is aligned); strip LF at the end + Filter to select and return only the employees that have been updated after `updated_since`. When it is used together with the `attributes[]` query parameter, the filter will select only the employees that have had any of the provided `attributes[]` updated since `updated_since`. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the `updated_since` filter, the `email`, `limit`, and `offset` parameters are ignored. + +
+ Examples with updated_since and attributes[]:
+ In an example company that has 17 employees:

+
+ + ?updated_since=2022-12-24T08:15:30 + will yield 10 employees that were recently updated: + + 


+            {
+              "success": true,
+              "metadata": {
+                "total_elements": 10,
+                "current_page": 0,
+                "total_pages": 10
+              },
+              "offset": 0,
+              "limit": 1,
+              "data": [
+                {
+                  "type": "Employee",
+                  "attributes": {
+                    "id": {
+                      "label": "ID",
+                      "value": 1,
+                      "type": "integer",
+                      "universal_id": "id"
+                    },
+                    "first_name": {
+                      "label": "First name",
+                      "value": "Alexander",
+                      "type": "standard",
+                      "universal_id": "first_name"
+                    },
+                    "last_name": {
+                      "label": "Last name",
+                      "value": "Bergmann",
+                      "type": "standard",
+                      "universal_id": "last_name"
+                    },
+                    "email": {
+                      "label": "Email",
+                      "value": "alexander.bergmann@demo.com",
+                      "type": "standard",
+                      "universal_id": "email"
+                    }
+                  }
+                }, ...
+              ],
+              ...
+              ...
+            }
+

+

+
+ + ?attributes[]=first_name + will yield all 17 employees: + + 


+            {
+              "success": true,
+              "metadata": {
+                "total_elements": 17,
+                "current_page": 0,
+                "total_pages": 17
+              },
+              "offset": 0,
+              "limit": 1,
+              "data": [
+                {
+                  "type": "Employee",
+                  "attributes": {
+                    "id": {
+                      "label": "ID",
+                      "value": 1,
+                      "type": "integer",
+                      "universal_id": "id"
+                    },
+                    "first_name": {
+                      "label": "First name",
+                      "value": "Alexander",
+                      "type": "standard",
+                      "universal_id": "first_name"
+                    }
+                  }
+                }
+              ]
+            }
+

+

+
+ + ?attributes[]=first_name&updated_since=2022-12-24T08:15:30 + will yield 3 employees, ones that had their first_name changed since 2022-12-24T08:15:30: + + 


+            {
+              "success": true,
+              "metadata": {
+                "total_elements": 3,
+                "current_page": 0,
+                "total_pages": 3
+              },
+              "offset": 0,
+              "limit": 1,
+              "data": [
+                {
+                  "type": "Employee",
+                  "attributes": {
+                    "id": {
+                      "label": "ID",
+                      "value": 1,
+                      "type": "integer",
+                      "universal_id": "id"
+                    },
+                    "first_name": {
+                      "label": "First name",
+                      "value": "Alexander",
+                      "type": "standard",
+                      "universal_id": "first_name"
+                    }
+                  }
+                }
+              ]
+            }
+

+
+
+ example: "2022-12-24T08:15:30" + schema: + type: string + example: 2022-12-24T08:15:30 description: List Company Employees responses: "200":