swagger: "2.0"
info:
  title: Events
  version: 1.0.0
  description: |
    ```plain {% title="Client ID" %}
    prod-nam-services-fdplan.slbservice.com
    prod-eu-services-fdplan.slbservice.com
    prod-au-services-fdplan.slbservice.com
    prod-id-services-fdplan.slbservice.com
    production-services-fdplan.slbservice.com
    ```

    The events API can be used to discover events which have occurred
    within FDPlan. The events follow the [cloud events specification](https://cloudevents.io/) for
    describing events.
    For more information on the [cloud event specification](https://github.com/cloudevents/spec).
  contact:
    name: SLB Customer Support for Digital
    url: https://customersupport.digital.slb.com
  x-product-id: FDPlan-Events
host: api.delfi.slb.com
basePath: /fdplan/events
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /v1/cloud-events:
    get:
      tags:
        - CloudEvents
      summary: Get a list of events
      description: Returns a list of events using CloudEvents. Due to paging this does not follow the standard 'batch' format, see [attributes](https://github.com/cloudevents/spec/blob/v0.3/json-format.md#2-attributes)
      operationId: getEvents
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - in: query
          description: An optional list of tags to filter events e.g. ["StudyId:01ED4CMJ4N9N504E3QJT1A68JY", "ScenarioId:01ED4CNEQDGBEWAK107ZFNT61S"]. The planning tags are typically of the form "tag name":"identifier". For example to query all events for the study with identifier "01ED4CMJ4N9N504E3QJT1A68JY" use ["StudyId:01ED4CMJ4N9N504E3QJT1A68JY"].
          name: planningtags
          type: array
          items:
            type: string
          collectionFormat: csv
          x-nullable: false
        - in: query
          description: Study identifier to filter results.  (Marked for deprecation in favour of planningtags)
          name: studyId
          type: string
          x-nullable: false
        - in: query
          description: First date from which events will be returned. Must be after 1979 and before 'to' filter, defaults to exactly 10 days ago.
          name: from
          type: string
          format: date-time
          x-example: "2021-01-01T00:00:00.000Z"
        - in: query
          description: Last date to which events will be returned. Must be either current time or after 'from', defaults to the current time.
          name: to
          type: string
          format: date-time
          x-example: "2021-01-10T00:00:00.000Z"
        - in: query
          description: Event type to filter results. The event type is a reverse DNS name of the form com.slb.cloud.fdplan.{domain}.{event-type}.{event-version}. where "domain" is the FDPlan domain which generated the results (e.g. studies, evaluation), "event-type" is the name of the event and "event-version" is the event version. For example, events are raised from the FDPlan evaluation system when computations are required and completed. The events have the form com.slb.cloud.fdplan.evaluation.computation_required_{spec_id}_{spec_version}.{event-version}, where "spec_id" and "spec_version" are the evaluation computation specification identifier and version respectively. See FDPlan evaluation API for more details.
          name: type
          type: string
          x-example: com.slb.cloud.fdplan.evaluation.computation_required_ix_v1.v1
        - in: query
          description: Paging - number of events to return in the current page.
          name: pageSize
          type: integer
          default: 50
          maximum: !!float 3600
        - in: query
          description: Paging - the current zero based index page.
          name: pageNumber
          type: integer
          default: 0
      responses:
        "200":
          description: Retrieved cloud events successfully.
          schema:
            $ref: '#/definitions/CloudEventsResponse'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
definitions:
  CloudEventsResponse:
    required:
      - events
      - total
    type: object
    properties:
      total:
        description: The total unpaged results for the filters given.
        type: integer
        example: 5
        x-nullable: false
      events:
        description: List of CloudEvents
        type: array
        items:
          $ref: '#/definitions/CloudEvent'
    example:
      events:
        - id: 01EHSM2HYX79AV6RRFSCYDR2YF
          specversion: "0.3"
          type: com.slb.cloud.fdplan.evaluation.computation_required_ix_v1.v1
          source: /services/internal/01EHSM2HYXM3MM99SH749MF53C
          time: "2021-01-04T14:24:52.189Z"
          datacontenttype: application/json
          studyId: 01ED4CMJ4N9N504E3QJT1A68JY
          planningtags:
            - StudyId:01ED4CMJ4N9N504E3QJT1A68JY
            - ScenarioId:01ED4CNEQDGBEWAK107ZFNT61S
          data:
            computationID: 1cc5d4b52ce9f3e4851024fdbba1bd028c0a25af1f140e6b92d27408e274403b
            specID: ix
            specName: name
            specVersion: 1
        - id: 01EHSM2HYX79AV6RRFSCYSDFSD
          specversion: "0.3"
          type: com.slb.cloud.fdplan.evaluation.computation_required_ix_v1.v1
          source: /services/internal/01EHSM2HYXM3MM99SH749MF53C
          time: "2021-01-09T14:24:52.189Z"
          datacontenttype: application/json
          studyId: 01ED4CMJ4N9N504E3QJT1A68JY
          planningtags:
            - StudyId:01ED4CMJ4N9N504E3QJT1A68JY
            - ScenarioId:01ED4CNEQDGBEWAK107ZFNT61S
          data:
            computationID: 543jk5hlk435hjlk435hk345hkhfkdjh55kjh5kjhsekjahklj60098092838098
            specID: ix
            specName: name
            specVersion: 1
      total: 2
  CloudEvent:
    required:
      - specversion
      - type
      - source
      - id
      - time
      - datacontenttype
      - studyId
      - data
    type: object
    properties:
      id:
        description: The identifier of the event. See [id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id).
        type: string
        example: 01EHSM2HYX79AV6RRFSCYDR2YF
        x-nullable: false
      specversion:
        description: The cloudevents spec version. See [version](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion).
        type: string
        example: "0.3"
        x-nullable: false
      type:
        description: The type of event being raised. The event type is a reverse DNS name of the form com.slb.cloud.fdplan.{domain}.{event-type}.{event-version}. where "domain" is the FDPlan domain which generated the results (e.g. studies, evaluation), "event-type" is the name of the event and "event-version" is the event version. For example, events are raised from the FDPlan evaluation system when computations are required and completed. The events have the form com.slb.cloud.fdplan.evaluation.computation_required_{spec_id}_{spec_version}.{event-version}, where "spec_id" and "spec_version" are the evaluation computation specification identifier and version respectively. See FDPlan evaluation API for more details. See [type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type).
        type: string
        example: com.slb.cloud.fdplan.evaluation.computation_completed_peep_economics_v1.v1
        x-nullable: false
      source:
        description: URI describing the origin of the event. See [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source).
        type: string
        example: /services/internal/01EHSM2HYXM3MM99SH749MF53C
        x-nullable: false
      time:
        format: date-time
        description: The time the event occurred (in memory) - note do not use an entity persistence time or any time which may lag the actual event. See [time](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#time).
        type: string
        example: "2020-09-09T14:24:52.189Z"
        x-nullable: false
      studyId:
        description: The study identifier. (Marked for deprecation in favour of planningtags)
        type: string
        example: 01ED4CMJ4N9N504E3QJT1A68JY
        x-nullable: false
      datacontenttype:
        description: The MIME content type of the 'data' field below. See [datacontenttype](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#datacontenttype).
        type: string
        example: application/json
        x-nullable: false
      planningtags:
        description: List of tags which will provide user context for logged events. Planning tags are typically of the form "tag name":"identifier".
        type: array
        items:
          type: string
        example:
          - StudyId:01ED4CMJ4N9N504E3QJT1A68JY
          - ScenarioId:01ED4CNEQDGBEWAK107ZFNT61S
      data:
        description: The JSON body of the event. See [data](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#data).
        additionalProperties: true
        type: object
        example:
          computationID: 1cc5d4b52ce9f3e4851024fdbba1bd028c0a25af1f140e6b92d27408e274403b
          specID: peep-economics
          specName: economics
          specVersion: 1
        x-nullable: false
    example:
      id: 01EHSM2HYX79AV6RRFSCYDR2YF
      specversion: "0.3"
      type: com.slb.cloud.fdplan.evaluation.computation_completed_peep_economics_v1.v1
      source: /services/internal/01EHSM2HYXM3MM99SH749MF53C
      time: "2020-09-09T14:24:52.189Z"
      studyId: 01ED4CMJ4N9N504E3QJT1A68JY
      datacontenttype: application/json
      planningtags:
        - StudyId:01ED4CMJ4N9N504E3QJT1A68JY
        - ScenarioId:01ED4CNEQDGBEWAK107ZFNT61S
      data:
        computationID: 1cc5d4b52ce9f3e4851024fdbba1bd028c0a25af1f140e6b92d27408e274403b
        specID: peep-economics
        specName: economics
        specVersion: 1
  Error:
    description: Generic error response.
    required:
      - data
    type: object
    properties:
      data:
        required:
          - code
        type: object
        properties:
          code:
            format: int32
            description: The HTTP status code.
            type: integer
            example: 500
            x-nullable: false
          message:
            description: The error message.
            type: string
            example: internal server error
    example:
      data:
        code: 500
        message: internal server error
parameters:
  SlbPartitionId:
    required: true
    in: header
    description: Data partition id.
    name: slb-partition-id
    type: string
security:
  - bearer: []
    appkey: []
securityDefinitions:
  bearer:
    type: apiKey
    name: Authorization
    in: header
  appkey:
    type: apiKey
    name: appkey
    in: header
tags:
  - name: CloudEvents
    description: Getting cloud events.