openapi.yaml

openapi: 3.0.0
info:
  title: Analytics
  description: A simple analytics API.
  version: 0.0.0
servers:
  - url: https://e1-analytics.herokuapp.com/1.0
  - url: http://localhost:3000/1.0
tags:
  - name: Events
    description: Events are the individual data points collected by the API. These events are stored in collections.
  - name: Projects
    description: Projects
components:
  securitySchemes:
    RootKey:
      type: apiKey
      in: header
      name: X-Root-Key
      description: The instance root key is used for managing projects.
    WriteKeyHeader:
      type: apiKey
      in: header
      name: Authorization
    WriteKeyQuery:
      type: apiKey
      in: query
      name: api_key

  schemas:
    CreateProjectScema:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Specifies the name of the project
          example: 'Test Project'
    ProjectScema:
      type: object
      required:
        - name
      properties:
        _id:
          type: string
          example: 5e19426836270c1b1e7b03f2
        name:
          type: string
          description: Specifies the name of the project
          example: 'Test Project'
        masterKey:
          type: string
          example: <MASTER_API_KEY>
        readKey:
          type: string
          example: <READ_API_KEY>
        writeKey:
          type: string
          example: <WRITE_API_KEY>
        createdAt:
          type: string
          example: '2020-01-11T13:38:05.006Z'
        updatedAt:
          type: string
          example: '2020-01-11T21:18:56.035Z'

  responses:
    BadRequestError:
      description: Missing or invalid parameters. Error messages will often contain more information to help you figure out what’s wrong.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'Failed to parse data.'
              error_code:
                type: string
                default: BadRequestError
    UnauthorizedError:
      description: API key is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'The API Key is invalid.'
              error_code:
                type: string
                default: UnauthorizedError
    NotFoundError:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'Resource not found.'
              error_code:
                type: string
                default: NotFoundError
    EventCreated:
      description: Event created successfully
      content:
        application/json:
          schema:
            type: object
            properties:
              created:
                type: boolean
                default: true
    Project:
      description: A project object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProjectScema'
    Projects:
      description: A project object
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ProjectScema'
  parameters:
    ProjectIdParam:
      in: path
      name: projectId
      schema:
        type: string
        example: 5e19426836270c1b1e7b03f2
      required: true
      description: ID of the project.
    CollectionNameParam:
      in: path
      name: collectionName
      schema:
        type: string
        example: your_event
      required: true
      description: Name of the event collection to record the event in.

paths:
  /projects/{projectId}/events/{collectionName}:
    post:
      summary: Record a single event
      security:
        - WriteKeyHeader: []
        - WriteKeyQuery: []
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectIdParam'
        - $ref: '#/components/parameters/CollectionNameParam'
      responses:
        '201':
          $ref: '#/components/responses/EventCreated'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      requestBody:
        description: Key value object of the event body
        required: false
        content:
          application/json:
            schema:
              type: object
              default: {}
              example: { key: 'value' }

    get:
      summary: Record a single event
      security:
        - WriteKeyHeader: []
        - WriteKeyQuery: []
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectIdParam'
        - $ref: '#/components/parameters/CollectionNameParam'
        - in: query
          name: data
          schema:
            type: string
          description: URL-encoded AND base-64 encoded event body
        - in: query
          name: redirect
          schema:
            type: string
          description: A URL to redirect the request toward after the event is recorded.
      responses:
        '201':
          $ref: '#/components/responses/EventCreated'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /projects:
    get:
      summary: Get projects
      security:
        - RootKey: []
      tags:
        - Projects
      responses:
        '200':
          $ref: '#/components/responses/Projects'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    post:
      summary: Create project
      security:
        - RootKey: []
      tags:
        - Projects
      requestBody:
        description: New project
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectScema'
      responses:
        '200':
          $ref: '#/components/responses/Project'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /projects/{projectId}:
    get:
      summary: Get project
      security:
        - RootKey: []
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectIdParam'
      responses:
        '200':
          $ref: '#/components/responses/Project'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    post:
      summary: Update project
      security:
        - RootKey: []
      tags:
        - Projects
      requestBody:
        description: Updated project
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectScema'
      parameters:
        - $ref: '#/components/parameters/ProjectIdParam'
      responses:
        '200':
          $ref: '#/components/responses/Project'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'