Operator API updates (#77)

mvp-spec/json-schemas/error.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Error",
+  "description": "The description of an error",
+  "$id": "error",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "message": {
+      "type": "string",
+      "description": "The error message"
+    }
+  },
+  "required": [
+    "message"
+  ]
+}

mvp-spec/json-schemas/get-3pc-request.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "get-3pc-request",
+  "title": "GET /v1/3pc request",
+  "type": "null",
+  "additionalProperties": false,
+  "description": "No parameter expected to call this endpoint"
+}

mvp-spec/json-schemas/get-3pc-response.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "get-3pc-response",
+  "title": "GET /v1/3pc response",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "3pc": {
+      "$ref": "test-3pc.json",
+      "description": "Value of `paf_test_3pc` if it was found (3rd party cookies are supported)\n\nIf 3rd party cookies are not supported, the endpoint returns `404` and an error message"
+    }
+  },
+  "required": [
+    "3pc"
+  ]
+}

mvp-spec/json-schemas/get-identity-request.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "get-identity-request",
+  "title": "GET /v1/identity request",
+  "type": "null",
+  "additionalProperties": false,
+  "description": "No parameter expected to call this endpoint"
+}

mvp-spec/json-schemas/get-identity-response.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "get-identity-response",
+  "title": "GET /v1/identity response",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the contracting party, since the domain may not reflect the company name.\n",
+      "examples": ["Criteo"]
+    },
+    "type": {
+      "type": "string",
+      "enum": ["vendor", "operator"],
+      "description": "The type of contracting party in the PAF ecosystem"
+    },
+    "version": {
+      "$ref": "version.json",
+      "description": "The type of contracting party in the PAF ecosystem"
+    },
+    "keys": {
+      "type": "array",
+      "description": "List of public keys the contracting party used or is using for signing data and messages",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Public key string value",
+            "examples": [
+              "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUnarwp0gUZgjb9fsYNLcNrddNKV5\nh4/WfMRMVh3HIqojt3LIsvUQig1rm9ZkcNx+IHZVhDM+hso2sXlGjF9xOQ==\n-----END PUBLIC KEY-----"
+            ]
+          },
+          "start": {
+            "$ref": "timestamp.json",
+            "description": "Timestamp when the contracting party started using this key for signing"
+          },
+          "end": {
+            "$ref": "timestamp.json",
+            "description": "Timestamp when the contracting party stopped using this key for signing"
+          }
+        },
+        "required": [
+          "key",
+          "start"
+        ]
+      }
+    }
+  },
+  "required": [
+    "name",
+    "type",
+    "version",
+    "keys"
+  ]
+}

mvp-spec/json-schemas/get-id-prefs-request.json → mvp-spec/json-schemas/get-ids-prefs-request.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "get-id-prefs-request",
-  "title": "GET /v1/id-prefs request",
+  "$id": "get-ids-prefs-request",
+  "title": "GET /v1/ids-prefs request",
   "type": "object",
   "additionalProperties": false,
   "properties": {

mvp-spec/json-schemas/get-ids-prefs-response.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "get-ids-prefs-response",
+  "title": "GET /v1/ids-prefs response",
+  "additionalProperties": false,
+  "properties": {
+    "sender": {
+      "$ref": "domain.json",
+      "description": "The domain name of the sender of this response (the operator domain name)"
+    },
+    "receiver": {
+      "$ref": "domain.json",
+      "description": "The domain name of the receiver of this request (the website)"
+    },
+    "timestamp": {
+      "$ref": "timestamp.json"
+    },
+    "signature": {
+      "$ref": "signature.json",
+      "description": "Signature based on input:\n```\nsender + '\\u2063' +\nreceiver + '\\u2063' +\ntimestamp + '\\u2063' +\npreferences.source.signature + '\\u2063' +\nidentifiers[0].source.signature + '\\u2063' +\nidentifiers[1].source.signature + '\\u2063' +\n...\nidentifiers[n].source.signature\n```"
+    },
+    "body": {
+      "$ref": "ids-and-optional-preferences.json"
+    }
+  },
+  "required": [
+    "sender",
+    "receiver",
+    "timestamp",
+    "signature",
+    "body"
+  ]
+}

mvp-spec/json-schemas/identifier.json

@@ -27,7 +27,8 @@
       "examples": ["7435313e-caee-4889-8ad7-0acd0114ae3c"]
     },
     "source": {
-      "$ref": "source.json"
+      "$ref": "source.json",
+      "description": "Signature based on input:\n\n```identifier.source.domain + '\\u2063' + \nidentifier.source.timestamp + '\\u2063' + \nidentifier.type + '\\u2063'+\nidentifier.value\n```"
     }
   },
   "required": [

mvp-spec/json-schemas/identifiers.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "List of identifiers",
+  "$id": "identifiers",
+  "type": "array",
+  "additionalProperties": false,
+  "items": {
+    "$ref": "identifier.json",
+    "description": "Signature based on input **that depends on the identifiers**:\n\n```identifier.source.domain + '\\u2063' + \nidentifier.source.timestamp + '\\u2063' + \nidentifier.type + '\\u2063'+\nidentifier.value\n```"
+  }
+}

mvp-spec/json-schemas/id-and-optional-preferences.json → mvp-spec/json-schemas/ids-and-optional-preferences.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "id-and-optional-preferences",
+  "$id": "ids-and-optional-preferences",
   "title": "Identifiers and optional preferences",
   "description": "A list of identifiers and optionally, some preferences",
   "type": "object",

mvp-spec/json-schemas/id-and-preferences.json → mvp-spec/json-schemas/ids-and-preferences.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Identifiers and preferences",
   "description": "A list of identifiers and some preferences",
-  "$id": "id-and-preferences",
+  "$id": "ids-and-preferences",
   "type": "object",
   "additionalProperties": false,
   "properties": {

mvp-spec/json-schemas/post-id-prefs-request.json → mvp-spec/json-schemas/post-ids-prefs-request.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "post-id-prefs-request",
-  "title": "POST /v1/id-prefs request",
+  "$id": "post-ids-prefs-request",
+  "title": "POST /v1/ids-prefs request",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -21,7 +21,7 @@
       "description": "Signature based on input:\n\n```\nsender + '\\u2063' +\nreceiver + '\\u2063' +\ntimestamp + '\\u2063' +\npreferences.source.signature + '\\u2063' +\nidentifiers[0].source.signature + '\\u2063' +\nidentifiers[1].source.signature + '\\u2063' +\n...\nidentifiers[n].source.signature\n```"
     },
     "body": {
-      "$ref": "id-and-preferences.json"
+      "$ref": "ids-and-preferences.json"
     }
   },
   "required": [

mvp-spec/json-schemas/get-id-prefs-response.json → mvp-spec/json-schemas/post-ids-prefs-response.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "get-id-prefs-response",
-  "title": "GET /v1/id-prefs response",
+  "$id": "post-ids-prefs-response",
+  "title": "POST /v1/ids-prefs response",
   "additionalProperties": false,
   "properties": {
     "sender": {
@@ -20,7 +20,7 @@
       "description": "Signature based on input:\n```\nsender + '\\u2063' +\nreceiver + '\\u2063' +\ntimestamp + '\\u2063' +\npreferences.source.signature + '\\u2063' +\nidentifiers[0].source.signature + '\\u2063' +\nidentifiers[1].source.signature + '\\u2063' +\n...\nidentifiers[n].source.signature\n```"
     },
     "body": {
-      "$ref": "id-and-optional-preferences.json"
+      "$ref": "ids-and-preferences.json"
     }
   },
   "required": [

mvp-spec/json-schemas/preferences.json

@@ -21,7 +21,8 @@
       "required": ["use_browsing_for_personalization"]
     },
     "source": {
-      "$ref": "source.json"
+      "$ref": "source.json",
+      "description": "Signature based on input:\n\n**⚠️ Note that it uses data from identifiers**:\n\n```preferences.source.domain + '\\u2063' +\npreferences.source.timestamp + '\\u2063' +\nidentifiers[type=\"prebid_id\"].source.signature + '\\u2063' +\npreferences.data.key1 + '\\u2063' + preferences.data[key1].value + '\\u2063' +\npreferences.data.key2 + '\\u2063' + preferences.data[key2].value + '\\u2063' +\n...\npreferences.data.keyN + '\\u2063' + preferences.data[keyN].value\n```"
     }
   },
   "required": [

mvp-spec/json-schemas/redirect-get-ids-prefs-request.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "redirect-get-ids-prefs-request",
+  "title": "GET /v1/redirect/get-ids-prefs request",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "returnUrl": {
+      "$ref": "return-url.json"
+    },
+    "request": {
+      "$ref": "get-ids-prefs-request.json"
+    }
+  },
+  "required": [
+    "returnUrl",
+    "request"
+  ]
+}