From 36346101110e3061c5ae497d52d8b2ebb088e688 Mon Sep 17 00:00:00 2001 From: Steven Richards Date: Fri, 8 Nov 2024 14:14:43 -0800 Subject: [PATCH 01/15] PLAT-786: Add event search API to spec --- .changeset/good-experts-watch.md | 5 + .changeset/orange-poets-drive.md | 5 + .../EventsGetSearchEventsResponse.yaml | 16 + .../components/schemas/Identification.yaml | 3 + schemas/fingerprint-server-api-for-sdks.yaml | 2 + schemas/paths/event-search.yaml | 145 ++++++++ .../examples/errors/400_bot_type_invalid.json | 6 + .../examples/errors/400_end_time_invalid.json | 6 + .../errors/400_ip_address_invalid.json | 6 + .../examples/errors/400_limit_invalid.json | 6 + .../errors/400_linked_id_invalid.json | 6 + .../errors/400_pagination_key_invalid.json | 6 + .../examples/errors/400_reverse_invalid.json | 6 + .../errors/400_start_time_invalid.json | 6 + .../paths/examples/get_event_search_200.json | 340 ++++++++++++++++++ 15 files changed, 564 insertions(+) create mode 100644 .changeset/good-experts-watch.md create mode 100644 .changeset/orange-poets-drive.md create mode 100644 schemas/components/schemas/EventsGetSearchEventsResponse.yaml create mode 100644 schemas/paths/event-search.yaml create mode 100644 schemas/paths/examples/errors/400_bot_type_invalid.json create mode 100644 schemas/paths/examples/errors/400_end_time_invalid.json create mode 100644 schemas/paths/examples/errors/400_ip_address_invalid.json create mode 100644 schemas/paths/examples/errors/400_limit_invalid.json create mode 100644 schemas/paths/examples/errors/400_linked_id_invalid.json create mode 100644 schemas/paths/examples/errors/400_pagination_key_invalid.json create mode 100644 schemas/paths/examples/errors/400_reverse_invalid.json create mode 100644 schemas/paths/examples/errors/400_start_time_invalid.json create mode 100644 schemas/paths/examples/get_event_search_200.json diff --git a/.changeset/good-experts-watch.md b/.changeset/good-experts-watch.md new file mode 100644 index 00000000..52c4ae61 --- /dev/null +++ b/.changeset/good-experts-watch.md @@ -0,0 +1,5 @@ +--- +'fingerprint-pro-server-api-openapi': minor +--- + +**events-search**: Add the new event search API diff --git a/.changeset/orange-poets-drive.md b/.changeset/orange-poets-drive.md new file mode 100644 index 00000000..7a3784a3 --- /dev/null +++ b/.changeset/orange-poets-drive.md @@ -0,0 +1,5 @@ +--- +'fingerprint-pro-server-api-openapi': minor +--- + +**events**: Add `suspect` field to the `Identification` \ No newline at end of file diff --git a/schemas/components/schemas/EventsGetSearchEventsResponse.yaml b/schemas/components/schemas/EventsGetSearchEventsResponse.yaml new file mode 100644 index 00000000..d8c36842 --- /dev/null +++ b/schemas/components/schemas/EventsGetSearchEventsResponse.yaml @@ -0,0 +1,16 @@ +components: + schemas: + EventsListResponse: + type: object + description: >- + Contains a list of events from all activated products + additionalProperties: false + required: + - events + properties: + events: + type: array + items: + $ref: 'EventsGetResponse.yaml' + paginationKey: + type: string \ No newline at end of file diff --git a/schemas/components/schemas/Identification.yaml b/schemas/components/schemas/Identification.yaml index 9e601c5a..a291d17c 100644 --- a/schemas/components/schemas/Identification.yaml +++ b/schemas/components/schemas/Identification.yaml @@ -33,6 +33,9 @@ properties: linkedId: type: string description: A customer-provided id that was sent with the request. + suspect: + description: Flag if the event has been tagged as suspicious or not. + type: boolean timestamp: description: Timestamp of the event with millisecond precision in Unix time. type: integer diff --git a/schemas/fingerprint-server-api-for-sdks.yaml b/schemas/fingerprint-server-api-for-sdks.yaml index ea2daacc..ec1c0351 100644 --- a/schemas/fingerprint-server-api-for-sdks.yaml +++ b/schemas/fingerprint-server-api-for-sdks.yaml @@ -29,6 +29,8 @@ security: - ApiKeyHeader: [] - ApiKeyQuery: [] paths: + /events/search: + $ref: 'paths/event-search.yaml' /events/{request_id}: $ref: 'paths/events.yaml' /visitors/{visitor_id}: diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml new file mode 100644 index 00000000..8f2431dc --- /dev/null +++ b/schemas/paths/event-search.yaml @@ -0,0 +1,145 @@ +get: + tags: + - Events + operationId: 'getEventSearch' + summary: Get events via search + description: | + Get one or more identification events, including Smart Signals, via searching. + Please note that the response includes mobile signals (e.g. `rootApps`) even if the request originated from a non-mobile platform. + It is highly recommended that you **ignore** the mobile signals for such requests. + If a `start` or `end` time are not supplied, the default search range is the last 7 days. + parameters: + - name: visitor_id + in: query + schema: + type: string + description: | + Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. + Filter for events matching this `visitor_id`. + - name: bot + in: query + schema: + type: string + enum: + - all + - good + - bad + - none + description: | + Filter events by the classification of bot type, specifically: + - all events classified as any kind of bot. + - events detected classified as a good bot. + - events detected classified as a bad bot. + - only non-bot events. + - name: ip_address + in: query + schema: + type: string + description: | + Filter events by IP address range. Range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6) + All ip_address filters must use CIDR notation, for example: 10.0.0.0/24, 192.168.0.1/32 + - name: linked_id + in: query + schema: + type: string + description: | + Filter events by your custom identifier. + + You can use [`linked_id`](https://dev.fingerprint.com/reference/get-function#linkedid) to associate identification requests with your own identifier, for example: session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier. + # example: some_id + - name: limit + in: query + required: true + schema: + type: integer + format: int32 + minimum: 1 + description: | + Limit the number of events returned. + - name: start + in: query + schema: + type: integer + format: int64 + description: | + Filter events with a timestamp greater than the start time, in unix time (milliseconds). + - name: end + in: query + schema: + type: integer + format: int64 + description: | + Filter events with a timestamp less than the end time, in unix time (milliseconds). + - name: reverse + in: query + schema: + type: boolean + description: | + Sort events in reverse timestamp order. + - name: suspect + in: query + schema: + type: boolean + description: | + Filter events previously tagged as suspicious via the [Update API](https://dev.fingerprint.com/reference/updateevent). + responses: + '200': + description: OK. + content: + application/json: + schema: + $ref: '../components/schemas/EventsGetSearchEventsResponse.yaml' + examples: + 200-full: + summary: Example response + externalValue: 'examples/get_event_search_200.json' + '403': + description: Forbidden. Access to this API is denied. + content: + application/json: + schema: + $ref: '../components/schemas/ErrorResponse.yaml' + examples: + 403-token-required: + summary: Error response when the secret API key was not provided. + externalValue: 'examples/errors/403_token_required.json' + 403-token-not-found: + summary: Error response when the provided secret API key does not exist. + externalValue: 'examples/errors/403_token_not_found.json' + 403-wrong-region: + summary: Error response when the API region is different from the region, the calling application is configured with. + externalValue: 'examples/errors/403_wrong_region.json' + '400': + description: Bad request. One or more supplied search parameters are invalid, or a required parameter is missing. + content: + application/json: + schema: + $ref: '../components/schemas/ErrorResponse.yaml' + examples: + 400-limit-invalid: + summary: Error response when no limit is supplied, or is invalid. + externalValue: 'examples/errors/400_limit_invalid.json' + 400-ip-address-invalid: + summary: Error response when an invalid IP address is supplied, or is not using CIDR notation. + externalValue: 'examples/errors/400_ip_address_invalid.json' + 400-bot-type-invalid: + summary: Error response when an invalid bot type is specified, must be one of good, bad, all, none. + externalValue: 'examples/errors/400_bot_type_invalid.json' + 400-reverse-invalid: + summary: Error response when the reverse parameter is invalid. + externalValue: 'examples/errors/400_reverse_invalid.json' + 400-start-time-invalid: + summary: Error response when an invalid start time is supplied. + externalValue: 'examples/errors/400_start_time_invalid.json' + 400-end-time-invalid: + summary: Error response when an invalid end time is supplied. + externalValue: 'examples/errors/400_end_time_invalid.json' + 400-visitor-id-invalid: + summary: Error response when an invalid visitor id is supplied. + externalValue: 'examples/errors/400_visitor_id_invalid.json' + 400-linked-id-invalid: + summary: Error response when an invalid linked id is supplied (too large). + externalValue: 'examples/errors/400_linked_id_invalid.json' + 400-pagination-key-invalid: + summary: Error response when an invalid pagination key is supplied. + externalValue: 'examples/errors/400_pagination_key_invalid.json' \ No newline at end of file diff --git a/schemas/paths/examples/errors/400_bot_type_invalid.json b/schemas/paths/examples/errors/400_bot_type_invalid.json new file mode 100644 index 00000000..8dd65266 --- /dev/null +++ b/schemas/paths/examples/errors/400_bot_type_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "invalid bot type" + } +} diff --git a/schemas/paths/examples/errors/400_end_time_invalid.json b/schemas/paths/examples/errors/400_end_time_invalid.json new file mode 100644 index 00000000..88654093 --- /dev/null +++ b/schemas/paths/examples/errors/400_end_time_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "invalid end time" + } +} \ No newline at end of file diff --git a/schemas/paths/examples/errors/400_ip_address_invalid.json b/schemas/paths/examples/errors/400_ip_address_invalid.json new file mode 100644 index 00000000..5969bab6 --- /dev/null +++ b/schemas/paths/examples/errors/400_ip_address_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "invalid ip address" + } +} \ No newline at end of file diff --git a/schemas/paths/examples/errors/400_limit_invalid.json b/schemas/paths/examples/errors/400_limit_invalid.json new file mode 100644 index 00000000..46297eb4 --- /dev/null +++ b/schemas/paths/examples/errors/400_limit_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "invalid limit" + } +} diff --git a/schemas/paths/examples/errors/400_linked_id_invalid.json b/schemas/paths/examples/errors/400_linked_id_invalid.json new file mode 100644 index 00000000..72de54e0 --- /dev/null +++ b/schemas/paths/examples/errors/400_linked_id_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "linked_id can't be greater than 256 characters long" + } +} diff --git a/schemas/paths/examples/errors/400_pagination_key_invalid.json b/schemas/paths/examples/errors/400_pagination_key_invalid.json new file mode 100644 index 00000000..df559f9a --- /dev/null +++ b/schemas/paths/examples/errors/400_pagination_key_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "invalid pagination key" + } +} diff --git a/schemas/paths/examples/errors/400_reverse_invalid.json b/schemas/paths/examples/errors/400_reverse_invalid.json new file mode 100644 index 00000000..540800fa --- /dev/null +++ b/schemas/paths/examples/errors/400_reverse_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "invalid reverse param" + } +} diff --git a/schemas/paths/examples/errors/400_start_time_invalid.json b/schemas/paths/examples/errors/400_start_time_invalid.json new file mode 100644 index 00000000..5d93f929 --- /dev/null +++ b/schemas/paths/examples/errors/400_start_time_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "invalid start time" + } +} \ No newline at end of file diff --git a/schemas/paths/examples/get_event_search_200.json b/schemas/paths/examples/get_event_search_200.json new file mode 100644 index 00000000..6cbbd6be --- /dev/null +++ b/schemas/paths/examples/get_event_search_200.json @@ -0,0 +1,340 @@ +{ + "events": [ + { + "products": { + "identification": { + "data": { + "visitorId": "Ibk1527CUFmcnjLwIs4A9", + "requestId": "1708102555327.NLOjmg", + "incognito": true, + "linkedId": "somelinkedId", + "tag": {}, + "time": "2019-05-21T16:40:13Z", + "timestamp": 1582299576512, + "url": "https://www.example.com/login?hope{this{works[!", + "ip": "61.127.217.15", + "ipLocation": { + "accuracyRadius": 10, + "latitude": 49.982, + "longitude": 36.2566, + "postalCode": "61202", + "timezone": "Europe/Dusseldorf", + "city": { + "name": "Dusseldorf" + }, + "country": { + "code": "DE", + "name": "Germany" + }, + "continent": { + "code": "EU", + "name": "Europe" + }, + "subdivisions": [ + { + "isoCode": "63", + "name": "North Rhine-Westphalia" + } + ] + }, + "browserDetails": { + "browserName": "Chrome", + "browserMajorVersion": "74", + "browserFullVersion": "74.0.3729", + "os": "Windows", + "osVersion": "7", + "device": "Other", + "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...." + }, + "confidence": { + "score": 0.97 + }, + "visitorFound": false, + "firstSeenAt": { + "global": "2022-03-16T11:26:45.362Z", + "subscription": "2022-03-16T11:31:01.101Z" + }, + "lastSeenAt": { + "global": null, + "subscription": null + } + } + }, + "botd": { + "data": { + "bot": { + "result": "notDetected" + }, + "url": "https://www.example.com/login?hope{this{works}[!", + "ip": "61.127.217.15", + "time": "2019-05-21T16:40:13Z", + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 YaBrowser/24.1.0.0 Safari/537.36", + "requestId": "1708102555327.NLOjmg" + } + }, + "rootApps": { + "data": { + "result": false + } + }, + "emulator": { + "data": { + "result": false + } + }, + "ipInfo": { + "data": { + "v4": { + "address": "94.142.239.124", + "geolocation": { + "accuracyRadius": 20, + "latitude": 50.05, + "longitude": 14.4, + "postalCode": "150 00", + "timezone": "Europe/Prague", + "city": { + "name": "Prague" + }, + "country": { + "code": "CZ", + "name": "Czechia" + }, + "continent": { + "code": "EU", + "name": "Europe" + }, + "subdivisions": [ + { + "isoCode": "10", + "name": "Hlavni mesto Praha" + } + ] + }, + "asn": { + "asn": "7922", + "name": "COMCAST-7922", + "network": "73.136.0.0/13" + }, + "datacenter": { + "result": true, + "name": "DediPath" + } + }, + "v6": { + "address": "2001:db8:3333:4444:5555:6666:7777:8888", + "geolocation": { + "accuracyRadius": 5, + "latitude": 49.982, + "longitude": 36.2566, + "postalCode": "10112", + "timezone": "Europe/Berlin", + "city": { + "name": "Berlin" + }, + "country": { + "code": "DE", + "name": "Germany" + }, + "continent": { + "code": "EU", + "name": "Europe" + }, + "subdivisions": [ + { + "isoCode": "BE", + "name": "Land Berlin" + } + ] + }, + "asn": { + "asn": "6805", + "name": "Telefonica Germany", + "network": "2a02:3100::/24" + }, + "datacenter": { + "result": false, + "name": "" + } + } + } + }, + "ipBlocklist": { + "data": { + "result": false, + "details": { + "emailSpam": false, + "attackSource": false + } + } + }, + "tor": { + "data": { + "result": false + } + }, + "vpn": { + "data": { + "result": false, + "confidence": "high", + "originTimezone": "Europe/Berlin", + "originCountry": "unknown", + "methods": { + "timezoneMismatch": false, + "publicVPN": false, + "auxiliaryMobile": false, + "osMismatch": false + } + } + }, + "proxy": { + "data": { + "result": false + } + }, + "incognito": { + "data": { + "result": false + } + }, + "tampering": { + "data": { + "result": false, + "anomalyScore": 0.1955, + "antiDetectBrowser": false + } + }, + "clonedApp": { + "data": { + "result": false + } + }, + "factoryReset": { + "data": { + "time": "1970-01-01T00:00:00Z", + "timestamp": 0 + } + }, + "jailbroken": { + "data": { + "result": false + } + }, + "frida": { + "data": { + "result": false + } + }, + "privacySettings": { + "data": { + "result": false + } + }, + "virtualMachine": { + "data": { + "result": false + } + }, + "rawDeviceAttributes": { + "data": { + "architecture": { + "value": 127 + }, + "audio": { + "value": 35.73832903057337 + }, + "canvas": { + "value": { + "Winding": true, + "Geometry": "4dce9d6017c3e0c052a77252f29f2b1c", + "Text": "dd2474a56ff78c1de3e7a07070ba3b7d" + } + }, + "colorDepth": { + "value": 30 + }, + "colorGamut": { + "value": "p3" + }, + "contrast": { + "value": 0 + }, + "cookiesEnabled": { + "value": true + }, + "cpuClass": {}, + "fonts": { + "value": ["Arial Unicode MS", "Gill Sans", "Helvetica Neue", "Menlo"] + } + } + }, + "highActivity": { + "data": { + "result": false + } + }, + "locationSpoofing": { + "data": { + "result": false + } + }, + "remoteControl": { + "data": { + "result": false + } + }, + "velocity": { + "data": { + "distinctIp": { + "intervals": { + "5m": 1, + "1h": 1, + "24h": 1 + } + }, + "distinctLinkedId": {}, + "distinctCountry": { + "intervals": { + "5m": 1, + "1h": 2, + "24h": 2 + } + }, + "events": { + "intervals": { + "5m": 1, + "1h": 5, + "24h": 5 + } + }, + "ipEvents": { + "intervals": { + "5m": 1, + "1h": 5, + "24h": 5 + } + }, + "distinctIpByLinkedId": { + "intervals": { + "5m": 1, + "1h": 5, + "24h": 5 + } + }, + "distinctVisitorIdByLinkedId": { + "intervals": { + "5m": 1, + "1h": 5, + "24h": 5 + } + } + } + }, + "developerTools": { + "data": { + "result": false + } + } + }} + ], + "paginationKey": "1655373953086" +} From 0d97f1587cf2af35d623126e6d9ea17e11886838 Mon Sep 17 00:00:00 2001 From: Steven Richards Date: Fri, 8 Nov 2024 14:23:38 -0800 Subject: [PATCH 02/15] fix tags --- schemas/fingerprint-server-api-for-sdks.yaml | 7 +++++-- schemas/paths/event-search.yaml | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/schemas/fingerprint-server-api-for-sdks.yaml b/schemas/fingerprint-server-api-for-sdks.yaml index ec1c0351..8b56e3ff 100644 --- a/schemas/fingerprint-server-api-for-sdks.yaml +++ b/schemas/fingerprint-server-api-for-sdks.yaml @@ -18,6 +18,9 @@ tags: - name: Related Visitors description: | Find visitor IDs that originated from a different browser on the same mobile device. + - name: Event Search + description: | + Using the Server API you can search for events matching one or more filters. servers: - url: https://api.fpjs.io description: Global @@ -29,8 +32,6 @@ security: - ApiKeyHeader: [] - ApiKeyQuery: [] paths: - /events/search: - $ref: 'paths/event-search.yaml' /events/{request_id}: $ref: 'paths/events.yaml' /visitors/{visitor_id}: @@ -39,6 +40,8 @@ paths: $ref: 'paths/webhook.yaml' /related-visitors: $ref: './paths/related-visitors.yaml' + /events/search: + $ref: 'paths/event-search.yaml' components: securitySchemes: ApiKeyHeader: diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml index 8f2431dc..b01445ac 100644 --- a/schemas/paths/event-search.yaml +++ b/schemas/paths/event-search.yaml @@ -1,6 +1,6 @@ get: tags: - - Events + - Event Search operationId: 'getEventSearch' summary: Get events via search description: | From 819abc074715a0ca1294d58c1c4c26ea0db95b52 Mon Sep 17 00:00:00 2001 From: Steven Richards Date: Fri, 8 Nov 2024 14:36:27 -0800 Subject: [PATCH 03/15] fix event search response schema --- .../schemas/EventsGetSearchEventsResponse.yaml | 16 ---------------- .../schemas/SearchEventsResponse.yaml | 18 ++++++++++++++++++ schemas/paths/event-search.yaml | 6 +++--- 3 files changed, 21 insertions(+), 19 deletions(-) delete mode 100644 schemas/components/schemas/EventsGetSearchEventsResponse.yaml create mode 100644 schemas/components/schemas/SearchEventsResponse.yaml diff --git a/schemas/components/schemas/EventsGetSearchEventsResponse.yaml b/schemas/components/schemas/EventsGetSearchEventsResponse.yaml deleted file mode 100644 index d8c36842..00000000 --- a/schemas/components/schemas/EventsGetSearchEventsResponse.yaml +++ /dev/null @@ -1,16 +0,0 @@ -components: - schemas: - EventsListResponse: - type: object - description: >- - Contains a list of events from all activated products - additionalProperties: false - required: - - events - properties: - events: - type: array - items: - $ref: 'EventsGetResponse.yaml' - paginationKey: - type: string \ No newline at end of file diff --git a/schemas/components/schemas/SearchEventsResponse.yaml b/schemas/components/schemas/SearchEventsResponse.yaml new file mode 100644 index 00000000..4d49138b --- /dev/null +++ b/schemas/components/schemas/SearchEventsResponse.yaml @@ -0,0 +1,18 @@ +type: object +description: >- + Contains a list of events from all activated products +additionalProperties: false +properties: + events: + type: array + items: + type: object + description: >- + Results for each identification event + required: + - products + properties: + products: + $ref: Products.yaml + paginationKey: + type: string \ No newline at end of file diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml index b01445ac..1b710f24 100644 --- a/schemas/paths/event-search.yaml +++ b/schemas/paths/event-search.yaml @@ -84,14 +84,14 @@ get: Filter events previously tagged as suspicious via the [Update API](https://dev.fingerprint.com/reference/updateevent). responses: '200': - description: OK. + description: Events matching the filter(s). content: application/json: schema: - $ref: '../components/schemas/EventsGetSearchEventsResponse.yaml' + $ref: '../components/schemas/SearchEventsResponse.yaml' examples: 200-full: - summary: Example response + summary: Example search results externalValue: 'examples/get_event_search_200.json' '403': description: Forbidden. Access to this API is denied. From 09ad3b1c8061afacec83573b3380a3a5ead2a868 Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Wed, 13 Nov 2024 18:05:12 +0000 Subject: [PATCH 04/15] chore: add path to readme explorer schema --- schemas/fingerprint-server-api-readme-explorer.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/schemas/fingerprint-server-api-readme-explorer.yaml b/schemas/fingerprint-server-api-readme-explorer.yaml index b6e9c9e3..730e026a 100644 --- a/schemas/fingerprint-server-api-readme-explorer.yaml +++ b/schemas/fingerprint-server-api-readme-explorer.yaml @@ -37,6 +37,8 @@ x-readme: paths: /events/{request_id}: $ref: 'paths/events.yaml' + /events/search: + $ref: 'paths/event-search.yaml' /visitors/{visitor_id}: $ref: 'paths/visitors.yaml' components: From eded9529a66affb8c02165bc2a230e66b4c4a4f1 Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Thu, 14 Nov 2024 09:45:09 +0100 Subject: [PATCH 05/15] fix: add `events-search` scope --- config/scopes.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/config/scopes.yaml b/config/scopes.yaml index d2926363..544cf92d 100644 --- a/config/scopes.yaml +++ b/config/scopes.yaml @@ -16,3 +16,7 @@ related-visitors: path: /related-visitors methods: - get +events-search: + path: /events/search + methods: + - get From 2a388d586ca8796e651f3e570edd7bf0ea650fcd Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Mon, 18 Nov 2024 16:45:37 +0000 Subject: [PATCH 06/15] chore: fix and simplify tags --- schemas/fingerprint-server-api-for-sdks.yaml | 18 +++++++++--------- ...fingerprint-server-api-readme-explorer.yaml | 7 +++++-- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/schemas/fingerprint-server-api-for-sdks.yaml b/schemas/fingerprint-server-api-for-sdks.yaml index 8b56e3ff..fcf32da1 100644 --- a/schemas/fingerprint-server-api-for-sdks.yaml +++ b/schemas/fingerprint-server-api-for-sdks.yaml @@ -11,16 +11,16 @@ info: tags: - name: Events description: | - Using the Server API you can retrieve information about individual analysis events using the event's `requestId`. + Retrieve or update information about individual events using the event's request ID. + - name: Event Search + description: | + Search for events matching one or more filters. - name: Visitors description: | - Using the Server API you can retrieve visitor history of individual visitors using their `visitorId`. + Retrieve all events of an individual visitor using their visitor ID. - name: Related Visitors description: | Find visitor IDs that originated from a different browser on the same mobile device. - - name: Event Search - description: | - Using the Server API you can search for events matching one or more filters. servers: - url: https://api.fpjs.io description: Global @@ -34,14 +34,14 @@ security: paths: /events/{request_id}: $ref: 'paths/events.yaml' + /events/search: + $ref: 'paths/event-search.yaml' /visitors/{visitor_id}: $ref: 'paths/visitors.yaml' - /webhook: - $ref: 'paths/webhook.yaml' /related-visitors: $ref: './paths/related-visitors.yaml' - /events/search: - $ref: 'paths/event-search.yaml' + /webhook: + $ref: 'paths/webhook.yaml' components: securitySchemes: ApiKeyHeader: diff --git a/schemas/fingerprint-server-api-readme-explorer.yaml b/schemas/fingerprint-server-api-readme-explorer.yaml index 730e026a..73119819 100644 --- a/schemas/fingerprint-server-api-readme-explorer.yaml +++ b/schemas/fingerprint-server-api-readme-explorer.yaml @@ -11,10 +11,13 @@ info: tags: - name: Events description: | - Using the Server API you can retrieve information about individual analysis events using the event's `requestId`. + Retrieve or update information about individual events using the event's `requestId`. + - name: Event Search + description: | + Search for events matching one or more filters. - name: Visitors description: | - Using the Server API you can retrieve visitor history of individual visitors using their `visitorId`. + Retrieve all events of an individual visitor using their `visitorId`. servers: - url: https://api.fpjs.io description: Global From e4336d05fdc263d1c3873c59f44e53d6789af851 Mon Sep 17 00:00:00 2001 From: Steven <89807676+srri@users.noreply.github.com> Date: Mon, 18 Nov 2024 10:34:03 -0800 Subject: [PATCH 07/15] chore: fixes after a review Co-authored-by: Juraj Uhlar --- schemas/components/schemas/Identification.yaml | 2 +- .../schemas/SearchEventsResponse.yaml | 4 ++-- schemas/paths/event-search.yaml | 17 ++++++++--------- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/schemas/components/schemas/Identification.yaml b/schemas/components/schemas/Identification.yaml index a291d17c..267a6004 100644 --- a/schemas/components/schemas/Identification.yaml +++ b/schemas/components/schemas/Identification.yaml @@ -34,7 +34,7 @@ properties: type: string description: A customer-provided id that was sent with the request. suspect: - description: Flag if the event has been tagged as suspicious or not. + description: `true` if you have previously set the `suspect` flag for this event using the [Server API Update event endpoint](https://dev.fingerprint.com/reference/updateevent). type: boolean timestamp: description: Timestamp of the event with millisecond precision in Unix time. diff --git a/schemas/components/schemas/SearchEventsResponse.yaml b/schemas/components/schemas/SearchEventsResponse.yaml index 4d49138b..1e8a621e 100644 --- a/schemas/components/schemas/SearchEventsResponse.yaml +++ b/schemas/components/schemas/SearchEventsResponse.yaml @@ -1,6 +1,6 @@ type: object description: >- - Contains a list of events from all activated products + Contains a list of all identification events matching the specified search criteria. additionalProperties: false properties: events: @@ -8,7 +8,7 @@ properties: items: type: object description: >- - Results for each identification event + Device intelligence results for the identification event. required: - products properties: diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml index 1b710f24..5e76ae66 100644 --- a/schemas/paths/event-search.yaml +++ b/schemas/paths/event-search.yaml @@ -4,10 +4,9 @@ get: operationId: 'getEventSearch' summary: Get events via search description: | - Get one or more identification events, including Smart Signals, via searching. - Please note that the response includes mobile signals (e.g. `rootApps`) even if the request originated from a non-mobile platform. - It is highly recommended that you **ignore** the mobile signals for such requests. - If a `start` or `end` time are not supplied, the default search range is the last 7 days. + Search for identification events, including Smart Signals, using multiple filtering criteria. If you don't provide `start` or `end` parameters, the default search range is the last 7 days. + + Please note that events include mobile signals (e.g. `rootApps`) even if the request originated from a non-mobile platform. We recommend you **ignore** mobile signals for such requests. parameters: - name: visitor_id in: query @@ -62,7 +61,7 @@ get: type: integer format: int64 description: | - Filter events with a timestamp greater than the start time, in unix time (milliseconds). + Filter events with a timestamp greater than the start time, in Unix time (milliseconds). - name: end in: query schema: @@ -107,7 +106,7 @@ get: summary: Error response when the provided secret API key does not exist. externalValue: 'examples/errors/403_token_not_found.json' 403-wrong-region: - summary: Error response when the API region is different from the region, the calling application is configured with. + summary: Error response when the API region does not match the region of your Fingerprint workspace. externalValue: 'examples/errors/403_wrong_region.json' '400': description: Bad request. One or more supplied search parameters are invalid, or a required parameter is missing. @@ -123,7 +122,7 @@ get: summary: Error response when an invalid IP address is supplied, or is not using CIDR notation. externalValue: 'examples/errors/400_ip_address_invalid.json' 400-bot-type-invalid: - summary: Error response when an invalid bot type is specified, must be one of good, bad, all, none. + summary: Error response when an invalid bot type is specified, must be one of `good`, `bad`, `all`, or `none`. externalValue: 'examples/errors/400_bot_type_invalid.json' 400-reverse-invalid: summary: Error response when the reverse parameter is invalid. @@ -135,10 +134,10 @@ get: summary: Error response when an invalid end time is supplied. externalValue: 'examples/errors/400_end_time_invalid.json' 400-visitor-id-invalid: - summary: Error response when an invalid visitor id is supplied. + summary: Error response when an invalid visitor ID is supplied. externalValue: 'examples/errors/400_visitor_id_invalid.json' 400-linked-id-invalid: - summary: Error response when an invalid linked id is supplied (too large). + summary: Error response when an invalid (too large) linked ID is supplied. externalValue: 'examples/errors/400_linked_id_invalid.json' 400-pagination-key-invalid: summary: Error response when an invalid pagination key is supplied. From 25d8d4bd40c086e8c738df8dede281397e342605 Mon Sep 17 00:00:00 2001 From: Steven Richards Date: Mon, 18 Nov 2024 10:46:23 -0800 Subject: [PATCH 08/15] move limit to top --- schemas/paths/event-search.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml index 5e76ae66..d285bfc7 100644 --- a/schemas/paths/event-search.yaml +++ b/schemas/paths/event-search.yaml @@ -8,6 +8,15 @@ get: Please note that events include mobile signals (e.g. `rootApps`) even if the request originated from a non-mobile platform. We recommend you **ignore** mobile signals for such requests. parameters: + - name: limit + in: query + required: true + schema: + type: integer + format: int32 + minimum: 1 + description: | + Limit the number of events returned. - name: visitor_id in: query schema: @@ -46,15 +55,6 @@ get: You can use [`linked_id`](https://dev.fingerprint.com/reference/get-function#linkedid) to associate identification requests with your own identifier, for example: session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier. # example: some_id - - name: limit - in: query - required: true - schema: - type: integer - format: int32 - minimum: 1 - description: | - Limit the number of events returned. - name: start in: query schema: From 642a1182a999b11e2d5033fd5ff6d5455e0b0627 Mon Sep 17 00:00:00 2001 From: Steven Richards Date: Mon, 18 Nov 2024 10:54:12 -0800 Subject: [PATCH 09/15] add new scope, fix suspect field --- config/scopes.yaml | 4 ++++ schemas/components/schemas/Identification.yaml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/config/scopes.yaml b/config/scopes.yaml index 544cf92d..7a68ddda 100644 --- a/config/scopes.yaml +++ b/config/scopes.yaml @@ -3,6 +3,10 @@ events: methods: - get - put +search: + path: /events/search + methods: + - get visitors: path: /visitors/{visitor_id} methods: diff --git a/schemas/components/schemas/Identification.yaml b/schemas/components/schemas/Identification.yaml index 267a6004..da177d26 100644 --- a/schemas/components/schemas/Identification.yaml +++ b/schemas/components/schemas/Identification.yaml @@ -34,7 +34,7 @@ properties: type: string description: A customer-provided id that was sent with the request. suspect: - description: `true` if you have previously set the `suspect` flag for this event using the [Server API Update event endpoint](https://dev.fingerprint.com/reference/updateevent). + description: Field is `true` if you have previously set the `suspect` flag for this event using the [Server API Update event endpoint](https://dev.fingerprint.com/reference/updateevent). type: boolean timestamp: description: Timestamp of the event with millisecond precision in Unix time. From c8491e148b08098f32e5c1eea1d8a72ea7e9687f Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Tue, 19 Nov 2024 13:09:54 +0000 Subject: [PATCH 10/15] chore: add limit example --- schemas/paths/event-search.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml index d285bfc7..785795cf 100644 --- a/schemas/paths/event-search.yaml +++ b/schemas/paths/event-search.yaml @@ -15,6 +15,7 @@ get: type: integer format: int32 minimum: 1 + example: 10 description: | Limit the number of events returned. - name: visitor_id From b5457d461a2526d6b8164a66aa4da2b76bbe26c6 Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Tue, 19 Nov 2024 14:30:10 +0100 Subject: [PATCH 11/15] chore: remove duplicated scope --- config/scopes.yaml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/config/scopes.yaml b/config/scopes.yaml index 7a68ddda..09a4392f 100644 --- a/config/scopes.yaml +++ b/config/scopes.yaml @@ -3,7 +3,7 @@ events: methods: - get - put -search: +events-search: path: /events/search methods: - get @@ -20,7 +20,3 @@ related-visitors: path: /related-visitors methods: - get -events-search: - path: /events/search - methods: - - get From 7ca04673d76d713f200c69a1f027fd50ca5cf626 Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Tue, 19 Nov 2024 15:13:18 +0100 Subject: [PATCH 12/15] chore: code review fixes Co-authored-by: Juraj Uhlar --- schemas/paths/event-search.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml index 785795cf..1eadeaa5 100644 --- a/schemas/paths/event-search.yaml +++ b/schemas/paths/event-search.yaml @@ -35,18 +35,18 @@ get: - bad - none description: | - Filter events by the classification of bot type, specifically: - - all events classified as any kind of bot. - - events detected classified as a good bot. - - events detected classified as a bad bot. - - only non-bot events. + Filter events by the bot detection result, specifically: + - events where any kind of bot was detected. + - events where a good bot was detected. + - events where a bad bot was detected. + - events where no bot was detected. - name: ip_address in: query schema: type: string description: | - Filter events by IP address range. Range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6) - All ip_address filters must use CIDR notation, for example: 10.0.0.0/24, 192.168.0.1/32 + Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6) + All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32 - name: linked_id in: query schema: @@ -54,7 +54,7 @@ get: description: | Filter events by your custom identifier. - You can use [`linked_id`](https://dev.fingerprint.com/reference/get-function#linkedid) to associate identification requests with your own identifier, for example: session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier. + You can use [linked IDs](https://dev.fingerprint.com/reference/get-function#linkedid) to associate identification requests with your own identifier, for example, session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier. # example: some_id - name: start in: query @@ -69,7 +69,7 @@ get: type: integer format: int64 description: | - Filter events with a timestamp less than the end time, in unix time (milliseconds). + Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). - name: reverse in: query schema: From 668de69eb796fe53cb5b2e75f503c4339d80237b Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Tue, 19 Nov 2024 14:21:59 +0000 Subject: [PATCH 13/15] chore: polish release notes --- .changeset/good-experts-watch.md | 2 +- .changeset/orange-poets-drive.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/good-experts-watch.md b/.changeset/good-experts-watch.md index 52c4ae61..0f651f95 100644 --- a/.changeset/good-experts-watch.md +++ b/.changeset/good-experts-watch.md @@ -2,4 +2,4 @@ 'fingerprint-pro-server-api-openapi': minor --- -**events-search**: Add the new event search API +**events-search**: Add a new events search API endpoint diff --git a/.changeset/orange-poets-drive.md b/.changeset/orange-poets-drive.md index 7a3784a3..27fc4354 100644 --- a/.changeset/orange-poets-drive.md +++ b/.changeset/orange-poets-drive.md @@ -2,4 +2,4 @@ 'fingerprint-pro-server-api-openapi': minor --- -**events**: Add `suspect` field to the `Identification` \ No newline at end of file +**events**: Add a `suspect` field to the `identification` product schema \ No newline at end of file From 6a1d4923a5d5b8d91680d2061ef9cf6ca414142e Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Tue, 19 Nov 2024 15:03:45 +0000 Subject: [PATCH 14/15] chore: expand release notes --- .changeset/good-experts-watch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/good-experts-watch.md b/.changeset/good-experts-watch.md index 0f651f95..fe1580fd 100644 --- a/.changeset/good-experts-watch.md +++ b/.changeset/good-experts-watch.md @@ -2,4 +2,4 @@ 'fingerprint-pro-server-api-openapi': minor --- -**events-search**: Add a new events search API endpoint +**events-search**: Add a new `events/search` API endpoint. Allow users to search for identification events matching one or more search criteria, for example, visitor ID, IP address, bot detection result, etc. From 2f1cfb72cca02da67f1d31fa4b9552dfe7b0594c Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Tue, 19 Nov 2024 16:29:26 +0100 Subject: [PATCH 15/15] chore: rename operationId for events search --- schemas/paths/event-search.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/schemas/paths/event-search.yaml b/schemas/paths/event-search.yaml index 1eadeaa5..63c57ac5 100644 --- a/schemas/paths/event-search.yaml +++ b/schemas/paths/event-search.yaml @@ -1,7 +1,7 @@ get: tags: - Event Search - operationId: 'getEventSearch' + operationId: 'searchEvents' summary: Get events via search description: | Search for identification events, including Smart Signals, using multiple filtering criteria. If you don't provide `start` or `end` parameters, the default search range is the last 7 days. @@ -142,4 +142,4 @@ get: externalValue: 'examples/errors/400_linked_id_invalid.json' 400-pagination-key-invalid: summary: Error response when an invalid pagination key is supplied. - externalValue: 'examples/errors/400_pagination_key_invalid.json' \ No newline at end of file + externalValue: 'examples/errors/400_pagination_key_invalid.json'