PLAT-786: Add event search API to spec

.changeset/good-experts-watch.md

@@ -0,0 +1,5 @@
+---
+'fingerprint-pro-server-api-openapi': minor
+---
+
+**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.

.changeset/orange-poets-drive.md

@@ -0,0 +1,5 @@
+---
+'fingerprint-pro-server-api-openapi': minor
+---
+
+**events**: Add a `suspect` field to the `identification` product schema

config/scopes.yaml

@@ -3,6 +3,10 @@ events:
   methods:
     - get
     - put
+events-search:
+  path: /events/search
+  methods:
+    - get
 visitors:
   path: /visitors/{visitor_id}
   methods:

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: 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.
     type: integer

schemas/components/schemas/SearchEventsResponse.yaml

@@ -0,0 +1,18 @@
+type: object
+description: >-
+  Contains a list of all identification events matching the specified search criteria.
+additionalProperties: false
+properties:
+  events:
+    type: array
+    items:
+      type: object
+      description: >-
+        Device intelligence results for the identification event.
+      required:
+        - products
+      properties:
+        products:
+          $ref: Products.yaml
+  paginationKey:
+    type: string

schemas/fingerprint-server-api-for-sdks.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 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.
@@ -31,12 +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'
+  /webhook:
+    $ref: 'paths/webhook.yaml'
 components:
   securitySchemes:
     ApiKeyHeader:

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
@@ -37,6 +40,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:

schemas/paths/event-search.yaml

@@ -0,0 +1,145 @@
+get:
+  tags:
+    - Event Search
+  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.
+
+    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
+        example: 10
+      description: |
+        Limit the number of events returned.
+    - 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 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. 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:
+        type: string
+      description: |
+        Filter events by 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
+      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 smaller 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: Events matching the filter(s).
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/SearchEventsResponse.yaml'
+          examples:
+            200-full:
+              summary: Example search results
+              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 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.
+      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`, or `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 (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.
+              externalValue: 'examples/errors/400_pagination_key_invalid.json'

schemas/paths/examples/errors/400_bot_type_invalid.json

@@ -0,0 +1,6 @@
+{
+  "error": {
+    "code": "RequestCannotBeParsed",
+    "message": "invalid bot type"
+  }
+}

schemas/paths/examples/errors/400_end_time_invalid.json

@@ -0,0 +1,6 @@
+{
+  "error": {
+    "code": "RequestCannotBeParsed",
+    "message": "invalid end time"
+  }
+}

schemas/paths/examples/errors/400_ip_address_invalid.json

@@ -0,0 +1,6 @@
+{
+  "error": {
+    "code": "RequestCannotBeParsed",
+    "message": "invalid ip address"
+  }
+}

schemas/paths/examples/errors/400_limit_invalid.json

@@ -0,0 +1,6 @@
+{
+  "error": {
+    "code": "RequestCannotBeParsed",
+    "message": "invalid limit"
+  }
+}

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"
+  }
+}

schemas/paths/examples/errors/400_pagination_key_invalid.json

@@ -0,0 +1,6 @@
+{
+  "error": {
+    "code": "RequestCannotBeParsed",
+    "message": "invalid pagination key"
+  }
+}

schemas/paths/examples/errors/400_reverse_invalid.json

@@ -0,0 +1,6 @@
+{
+  "error": {
+    "code": "RequestCannotBeParsed",
+    "message": "invalid reverse param"
+  }
+}

schemas/paths/examples/errors/400_start_time_invalid.json

@@ -0,0 +1,6 @@
+{
+  "error": {
+    "code": "RequestCannotBeParsed",
+    "message": "invalid start time"
+  }
+}