cxsSwagger.yaml

swagger: '2.0'
info:
  title: CXS REST API
  description: Specification of the CXS Oasis Standard 
  version: "1.0.0"
# the domain of the service
host: cxs.oasisopen.org
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:
  /scopes/{scopeId}/events/_collect:
    post:
      summary: An endpoint for data collection
      description: |
        Collect single or batched events from any client. This endpoint doesn't require any authentication but requires a valid trackingId. 
      parameters:
        - $ref: '#/parameters/scopeId'
        - name: payload
          description: An array of Event objects
          in: body
          schema:
            $ref: '#/definitions/eventBody'
      tags:
        - Event
      responses:
        204:
          description: No response returned in order to optimize performance
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'


  /scopes/{scopeId}/events:
    get:
      summary: Event retrieval by query
      description: |
        This api enables retrieval of events using simple query parameters 
      parameters:
        - $ref: '#/parameters/scopeId'
        - $ref: '#/parameters/properties'
        - $ref: '#/parameters/pageSize'
        - $ref: '#/parameters/offset'
#        - $ref: '#/parameters/eventTypes'
#        - $ref: '#/parameters/subjectId'
#        - $ref: '#/parameters/geoArea'
#        - $ref: '#/parameters/fromTime'
#        - $ref: '#/parameters/toTime'
#        - $ref: '#/parameters/trackerId'
# Optionally provide the most common used query parameters in get requests.
        - $ref: '#/parameters/orderBy'
      tags:
        - Event
        - Query
      responses:
        200:
          description: An array of events
          schema:
           $ref: '#/definitions/EventResult'
          examples: 
            application/json:
              { 
                total: 2000, offset: 0, pageSize: 2,
                orderBy: [{ propertyName: "firstName", order:"DESC" }], 
                hits: [{_id: 1, firstName: 'Novak'}, {_id: 2, firstName: 'Grigor'}]
              }
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Creates a new event
      description: This method is used to create a new event. This will return the created event while the collect endpoint will not. Compared to _collect it will only support single objects and be more verbose, and typically require some authentication
      parameters:
        - $ref: '#/parameters/scopeId'
        - name: payload
          description: An array of Event objects
          in: body
          schema:
            $ref: '#/definitions/eventBody'
      tags:
        - Event
      responses:
        201:
          description: Result of event creation TODO-define the response object
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error' 


  /scopes/{scopeId}/events/_query:
    post:
      summary: Event retrieval by query
      description: |
        This api enables retrieval of events through complex queries 
      parameters:
        - $ref: '#/parameters/scopeId'
        - name: query
          description: Event query definition
          in: body
          schema:
            $ref: '#/definitions/Query'
      tags:
        - Event
        - Query
      responses:
        200:
          description: An array of events
          schema:
           $ref: '#/definitions/EventResult'
          examples: 
            application/json:
              { 
                total: 2000, offset: 0, pageSize: 2,
                orderBy: [{ propertyName: "firstName", order:"DESC" }], 
                hits: [{_id: 1, firstName: 'Novak'}, {_id: 2, firstName: 'Grigor'}]
              }
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'


  /scopes/{scopeId}/types/event:
    get:
      summary: An endpoint returning all available event types
      description: |
        All known event types to this context server. 
      parameters:
        - $ref: '#/parameters/scopeId'
        - $ref: '#/parameters/pageSize'
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/orderBy'
      tags:
        - Event
      responses:
        200:
          description: An array of event types
          schema:
           $ref: '#/definitions/EventTypeResult'
          examples: 
            application/json:
              { 
                total: 2000, offset: 0, pageSize: 2,
                hits: [
                  {id: 'pageView', description: 'User has visited a web page', schema: {
                          properties: {
                        		pageTitle: {
                        			type: 'string'
                        		},
                        		tags: {
                        			type: 'string'
                        		}
                        	},
                        	required: []
                        }
                  }
                ]
              }  
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'




  /scopes/{scopeId}/profiles:
    get:
      summary: Profile retrieval by simple query
      description: |
        Access all profiles matching a simple query based
        on matching a single property to a value. The resulsts will automatically be ordered by natural ascending order of the specified property. This endpoint could for example be used to implement
        auto-completion mechanisms
      parameters:
        - $ref: '#/parameters/scopeId'
        - $ref: '#/parameters/simpleQueryPropertyName'
        - $ref: '#/parameters/simpleQueryPropertyValue'
        - $ref: '#/parameters/properties'
        - $ref: '#/parameters/pageSize'
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/reverseOrder'
      tags:
        - Profile
        - Query
      responses:
        200:
          description: An array of profiles
          schema:
           $ref: '#/definitions/ProfileResult'
          examples: 
            application/json:
              { 
                total: 2000, offset: 0, pageSize: 2,
                orderBy: [{ propertyName: "firstName", order:"DESC" }], 
                hits: [{_id: 1, firstName: 'Novak'}, {_id: 2, firstName: 'Grigor'}]
              }
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

# WG3 suggest dropping create profile, and rather use an import API for this specific use case.
# As such profiles are never manually created, but rise from events of a given tracker rules and merges
# Editing is however a natural feature

    post:
      summary: Creates a new profile.
      description: This method is used to create a new profile coming from an external source, with an external source unique name and an external profile identifier. The context server will generate or resolve from a merge a unified profile identifier.
      parameters:
        - $ref: '#/parameters/scopeId'
        - $ref: '#/parameters/profileBody'
      tags:
        - Profile
      responses:
        201:
          description: Profile creation returns the created profile.
          schema:
           $ref: '#/definitions/Profile'
          examples: 
            application/json:
              { 
                _id: 1, firstName: 'Novak'
              }
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /scopes/{scopeId}/profiles/_query:
    post:
      summary: Profile retrieval by query
      description: |
        This api enables retrieval of profiles through complex query
      parameters:
        - $ref: '#/parameters/scopeId'
        - name: query
          description: Profile query definition
          in: body
          schema:
            $ref: '#/definitions/Query'
      tags:
        - Profile
        - Query
      responses:
        200:
          description: An array of profiles
          schema:
           $ref: '#/definitions/ProfileResult'
          examples: 
            application/json:
              { 
                total: 2000, offset: 0, pageSize: 2,
                orderBy: [{ propertyName: "firstName", order:"DESC" }], 
                hits: [{_id: 1, firstName: 'Novak'}, {_id: 2, firstName: 'Grigor'}],
                # should we have this aggregates complexity?
                aggregates: [{name : "averageAge", value: 20.54}, {name : "birthYearProfileCount", value: {2010 : 10, 2011 : 12}}]
              }
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
            
            
  /scopes/{scopeId}/profiles/{profileId}:
    get:
      summary: Get explicit profile
      description: Access a specific profile.
      parameters:
        - $ref: '#/parameters/scopeId'
        - name: profileId
          in: path
          description: Specify the profiles unique ID
          type: string
          required: true
      tags:
        - Profile
      responses:
        200:
          description: A single profile
          schema:
              $ref: '#/definitions/Profile'
          examples:
            application/json:
              { _id: 1, firstName: 'Novak'}
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'


################################################################################
#                                   Parameters                                 #
################################################################################
parameters:
  scopeId:
    name: scopeId
    in: path
    description: In order to provide multitenancy, cxs servers should implement scopes. If the implementation does not support scopes, the name default can be used i.e. /v1/scopes/default/. Scope ID's are obtained from the context server by creating new scopes. (Alternative we could use "Tenant")
    required: true
    type: string
  simpleQueryPropertyName:
    name: propName
    in: query
    description: Name of the property to match a value against (value specified in "propValue" parameter). Implementations might allow for wildcards characters
    required: true
    type: string
  simpleQueryPropertyValue:
    name: propValue
    in: query
    description: Value of the property specified in "propName" to make against. Implementations might allow values to include wildcards or regular expressions
    required: true
    type: string
  properties:
    name: properties
    in: query
    description: Specify the properties to be returned, use * to return all. If not specified, identifier property will be returned (hmm. should we force developers to specify properties?)
    required: false
    type: array
    items:
      type: string
  pageSize:
    name: pageSize
    in: query
    description: Number of items to be returned
    required: false
    type: number
    format: long
  offset:
    name: offset
    in: query
    description: Offset in number of items in query result set
    required: false
    type: number
    format: long
  orderBy:
    name: orderBy
    in: query
    description: Specify property to order query results by
    required: false
    type: string
    format: propertyName ASC | DESC
#  queryBody:
#    name: query
#    in: body
#    description: Specifies the query to filter items by
#    required: false
#    schema:
#      $ref: '#/definitions/Query'
  reverseOrder:
    name: reverse
    in: query
    description: If true, the query results will be in reverse order
    required: false
    type: boolean
    format: truthy, any value apart from false or 0 will be true

  profileBody:
    name : profile
    in: body
    description : Represents the contents of a profile in the body of a request, i.e. with no ID
    schema:
      type: object
      

################################################################################
#                                 Definitions                                  #
################################################################################
definitions:
  eventBody:
    type: object
    properties:
      trackerId:
        type: string
        format: uuid
      events:
        type: array
        items:
         $ref: '#/definitions/CreateEvent'

  QueryClause:
    type: object
    description: A query clause
    allOf:
      - $ref: '#/definitions/FunctionCall'
      - type: object
        properties:
          op:
            type: string
          args:
            type: array
            items:
              $ref: '#/definitions/QueryClause'

  IntLiteral:
    type: integer
    format: int64

  DoubleLiteral:
    type: number
    format: double

  BooleanLiteral:
    type: boolean

  StringLiteral:
    type: string

  DateLiteral:
    type: string
    format: 'date-time'
  
  FunctionLiteral:
    type: object
    description: A function call.

# How to specify that it will take any of the possible arguments
  FunctionCall:
    type: object
    properties:
      function:
        type : string
      arguments:
        type : array
        items : 
            - $ref: '#/definitions/FunctionLiteral'
            - $ref: '#/definitions/IntLiteral'
            - $ref: '#/definitions/DoubleLiteral'
            - $ref: '#/definitions/BooleanLiteral'
            - $ref: '#/definitions/StringLiteral'
            - $ref: '#/definitions/DateLiteral'


  Query:
    type: object
    description: A container for query projections, operations, arguments and order by clauses
    properties:
      properties:
        type: array
        description : a list of property names to that will be return in the query result.
        items:
          type: string
      pageSize:
        type: integer
        description: number of items per page
      offset:
        type: integer
        description: Return result in offset number of items from first item
      filter:
        $ref: '#/definitions/FunctionCall'
      aggregations:
        type: object
        description: defines what data aggregation to return (optional)
        example: TODO-reuse the concept of query function definitions?
      orderBy:
        type: array
        items :
          $ref: '#/definitions/OrderByPart'


#	{
#		"properties" : ['firstName', 'lastName']
#		"filter" : {
#			"function" : 'and',
#			"arguments" : [{
#					"function": "gt",
#					"arguments": [
#						{
#							"function" : 'geoDistance',
#							"argument" :  ['geoLocation', {l: 43, a: 56}]
#						},
#						100 //100 meters
#					]
#				}, {
#					"function" : 'in',
#					"arguments" : ['views', 1, 2, 3]
#				}
#			]
#		},
#		"orderBy" : [{
#				"propertyName" : 'firstName' "order" : 'DESC'
#			}, {
#				"propertyName" : 'lastName'
#			}
#		]
#	}




  ProfileResult:
    type: object
    allOf:
      - $ref: '#/definitions/QueryResult'
      - type: object
        properties:
          hits:
            type: array
            description: Query result
            items:
              $ref: '#/definitions/Profile'

  Profile:
    type: object
    properties:
      _id:
        type: string
        format: uuid
    additionalProperties:
      type: object

  EventResult:
    type: object
    allOf:
      - $ref: '#/definitions/QueryResult'
      - type: object
        properties:
          hits:
            type: array
            description: Query result
            items:
              $ref: '#/definitions/Event'          
  
  
  EventTypeResult:
    type: object
    properties:
      total:
        type: number
        format: long
        description: Total number of event types
      offset:
        type: number
        format: long
        description: The requested offset in number of items, starting at 0
      pageSize:
        type: number
        format: short
        description: Requested number of items to be returned
      hits:
        type: array
        description: result
        items:
          $ref: '#/definitions/EventType'
          
  EventType:
    type: object
    properties:
      id:
        type: string
        description: the unique identifier of th event type. Custom event types mist be prefixed with namespace for example mycompany.<eventTypeId>.
      schema:
        type: object
        description: JSON schema for optional event's data. For more info see http://json-schema.org/documentation.html



  CreateEvent:
    type: object
    properties:
# Hmm reuse from event definition?
      eventType: 
        type: string
        description: The type of the current event. Eg. PageView, Click, Hover, Scroll, Bought, MailShot...
      objectId: 
        type: string
        description: The item/object the user interacted with. Eg. Page URL, Product Name, Mail shot Id...
      subjectId:
        type: string
        description: Source unique id identifying the web page visitor or contact in the CRM system. The id can be optained from cookie or directly from the source system. The used tracking id should be bound to a specific source. If a unique id cannot be generated, the context server can issue one for you.
      geoLocation:
        type: string
        format: geoPoint
        description: TBD
      timestamp:
        type: string
        format: date-time
        description: If not specified, the context server uses time of submission.
      data:
        type: object
        description: Optional event specific information.
    required: ['eventType', 'objectId', 'subjectId']
  
  Event:
    type: object
    properties:
      _id:
        type: string
      eventType: 
        type: string
        description: the type of the current event
        # should we name it object, item or other instead?
      objectId: 
        type: string
        description: The item/object the user interacted with
        # Should the Profile Id be available also as a cookie?
      subjectId:
        type: string
      geoLocation:
        type: string
        format: geoPoint
        description: TBD
      timestamp:
        type: string
        format: date-time
        description: If not specified, the context server uses time of submission.
      data:
        type: object
        description: Optional event specific information.
    required: ['eventType', 'objectId', 'subjectId']

      
  QueryResult:
    type: object
    discriminator: resultType
    required:
      - resultType # required for inheritance to work
    properties:
      resultType:
        type: string
      total:
        type: number
        format: long
        description: Total number of objects matching this query
      offset:
        type: number
        format: long
        description: The requested offset in number of items, starting at 0
      pageSize:
        type: number
        format: short
        description: Requested number of items to be returned
      orderBy:
        type: array
        items:
          $ref: '#/definitions/OrderByPart'
      aggregates:
        type: array
        items:
          $ref: '#/definitions/AggregatesPart'

  OrderByPart:
    type: object
    description: A single part of a orderBy clause
    properties: 
      propertyName:
        type: string
        description : This parameter is required
      order: 
        type: string
        format: DESC
        description : This parameter is optional, if not specified it will default to ASC

  AggregatesPart:
    type: object
    description: Result of an aggregation executed by a query.
    properties: 
      name:
        type: string
        description : Name of the aggregation as specified in the query.
      value: 
        type: object
        description : Result of the aggregation function.

  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string