spec.yml

openapi: 3.0.2
info:
  description: >-
    This great API aims to provide endpoints to notify blablacar user or anonymous
    user devices (email, sms, viber, push).
  version: 0.0.1
  title: Blablacar Communication Service
  termsOfService: ''
  contact:
    email: team-v3@blablacar.com
servers:
- url: communication.blablacar.docker/api/v1
  description: Local server
- url: 'http://communication-service.svc.prod.par-3.h.blbl.cr/api/v1'
  description: Prod server
security:
- ApiKeyAuth: []
tags:
- name: scenario
  description: Everything about scenarios
- name: template
  description: Everything about templates
paths:
  '/notification/check/{uuid}/{path}':
    get:
      tags:
      - notification check
      summary: Check if template is allowed
      description: >-
        Use this endpoint to check if a given user has accepted to receive a
        given template
      parameters:
      - in: path
        name: path
        required: true
        schema:
          type: string
        description: The path of the template
      - in: path
        name: uuid
        required: true
        schema:
          type: string
          format: uuid
        description: The user uuid
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationCheckResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '500':
          $ref: '#/components/responses/ServerErrorResponse'
  '/api/v1/notification/send/{uuid}':
    post:
      tags:
      - notification send
      summary: Trigger a notification to be sent
      description: >-
        Use this endpoint to send a notification
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
          format: uuid
        description: the notification uuid
      responses:
        '200':
          description: Ok
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '500':
          $ref: '#/components/responses/ServerErrorResponse'
  /api/v1/notification/send/email:
    post:
      tags:
      - email send
      summary: Send an email
      description: >-
        Use this endpoint to send an email immediately
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailCreationRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCreationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '500':
          $ref: '#/components/responses/ServerErrorResponse'
  /scenario:
    post:
      tags:
      - scenario
      summary: Create a new scenario
      description: >-
        Use this endpoint to create new communication scenario where you can
        define which notifications you want to sent to end user
      operationId: createScenario
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                notifications:
                  type: array
                  items:
                    $ref: '#/components/schemas/ScenarioCreationRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationCreationResponse'
        '400':
          $ref: '#/components/responses/InvalidErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '409':
          description: Conflict Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DuplicateScenarioError'
        '500':
          $ref: '#/components/responses/ServerErrorResponse'
  '/scenario/{uuid}':
    get:
      tags:
      - scenario
      summary: Get a scenario
      description: >-
        Use this endpoint to get some informations about a communication
        scenario
      operationId: getScenario
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
          format: uuid
        description: The communication uuid
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scenario'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '500':
          $ref: '#/components/responses/ServerErrorResponse'
  '/template/{path}':
    get:
      tags:
      - template
      summary: Get a template
      description: >-
        Use this endpoint to get some informations about a communication
        template
      operationId: getTemplate
      parameters:
      - in: path
        name: path
        required: true
        schema:
          type: string
        description: The path to the template
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '500':
          $ref: '#/components/responses/ServerErrorResponse'
  '/recipients/{uuid}':
    get:
      tags:
      - recipient
      summary: Get recipient info
      description: Use this endpoint to get recipient info to send notifications
      operationId: getRecipient
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
        description: The recipient uuid
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '500':
          $ref: '#/components/responses/ServerErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  responses:
    ServerErrorResponse:
      description: Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
    NotFoundErrorResponse:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    InvalidErrorResponse:
      description: Invalid Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
    UnauthorizedErrorResponse:
      description: API key is missing or invalid
      headers:
        WWW_Authenticate:
          schema:
            type: string
            example: Apikey
  schemas:
    RequestError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: request_error
        code:
          type: integer
          example: 100
        context:
          type: array
          items:
            type: string
      oneOf:
      - $ref: '#/components/schemas/InvalidRequestError'
      - $ref: '#/components/schemas/BusinessRequestError'
      - $ref: '#/components/schemas/NotFoundError'
      - $ref: '#/components/schemas/ServerError'
    NotFoundError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: not_found
        code:
          type: integer
          example: 110
        context:
          type: array
          items:
            type: string
    InvalidRequestError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: invalid_request
        code:
          type: integer
          example: 101
        field:
          type: string
          example: expire_at
        context:
          type: array
          items:
            type: string
      oneOf:
      - $ref: '#/components/schemas/InvalidExpirationDateError'
      - $ref: '#/components/schemas/MissingContextDataError'
    BusinessRequestError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: business_error
        code:
          type: integer
          example: 102
        context:
          type: array
          items:
            type: string
      oneOf:
      - $ref: '#/components/schemas/RecipientNotFoundError'
      - $ref: '#/components/schemas/TooBigContextDataError'
      - $ref: '#/components/schemas/NotificationTemplateNotFoundError'
      - $ref: '#/components/schemas/InvalidExpirationDateError'
    ServerError:
      type: object
      oneOf:
      - $ref: '#/components/schemas/UnableToFetchRecipientError'
      - $ref: '#/components/schemas/UnableToAcknowledgeRequestError'
    DuplicateScenarioError:
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: duplicate_scenario
        code:
          type: integer
          example: 103
        context:
          type: array
          items:
            type: string
    TooBigContextDataError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: too_big_context_data
        code:
          type: integer
          example: 104
        context:
          type: array
          items:
            type: string
    RecipientNotFoundError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: invalid_recipient
        code:
          type: integer
          example: 105
        context:
          type: array
          items:
            type: string
    NotificationTemplateNotFoundError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: template_not_found
        code:
          type: integer
          example: 106
        context:
          type: array
          items:
            type: string
    InvalidExpirationDateError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: invalid_expiration_date
        code:
          type: integer
          example: 107
        context:
          type: array
          items:
            type: string
    MissingContextDataError:
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: missing_context_data
        code:
          type: integer
          example: 108
        context:
          type: array
          items:
            type: string
    UnableToFetchRecipientError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: unable_to_fetch_recipient
        code:
          type: integer
          example: 107
        context:
          type: array
          items:
            type: string
    UnableToAcknowledgeRequestError:
      type: object
      required:
      - service
      - type
      - code
      - context
      properties:
        service:
          type: string
          example: communication
        type:
          type: string
          example: unable_to_acknowledge_request
        code:
          type: integer
          example: 107
        context:
          type: array
          items:
            type: string
    Template:
      type: object
      properties:
        key:
          type: string
          example: text_message/driver/booking
          description: The unique identifier of the template
        required_data:
          type: array
          description: The required context data to populate the template with
          items:
            type: string
        sender:
          type: string
          example: Blablacar
          description: The sender name to display for the template
    Recipient:
      type: object
      properties:
        id:
          type: integer
          description: The legacy user id
        uuid:
          type: string
          description: The user uuid
        civility:
          type: string
          description: The user civility
        firstname:
          type: string
          description: The user firstname
        lastname:
          type: string
          description: The user lastname
        locale:
          type: array
          xml:
            name: locale
            wrapped: true
          items:
            $ref: '#/components/schemas/Locale'
        phone_number:
          type: array
          xml:
            name: phone_number
            wrapped: true
          items:
            $ref: '#/components/schemas/PhoneNumber'
    Locale:
      type: object
      properties:
        value:
          type: string
          description: The locale
        id:
          type: string
          description: The locale id
    PhoneNumber:
      type: object
      properties:
        country_code:
          type: string
          description: The country phone prefix
        national_number:
          type: string
          description: The national phone number part
        raw_input:
          type: string
          description: The phone number
        region_code:
          type: string
          description: The phone code region
    Scenario:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: fd341be6-b2bb-45c6-9128-eaad6d6c8581
          description: The unique identifier of the scenario
        status:
          type: string
          enum:
          - SCHEDULED
          - IN_PROGRESS
          - DONE
          - CANCELLED
          - FAILED
          example: SCHEDULED
          description: The current status of the scenario
        notifications:
          type: array
          xml:
            name: notification
            wrapped: true
          items:
            $ref: '#/components/schemas/Notification'
    EmailCreationRequest:
      type: object
      properties:
        to:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                format: email
                example: toto@blablacar.com
                description: Set the email address to be used
              name:
                type: string
                example: Mr Toto
                description: Set the email alias to be used
        subject:
          type: string
          example: Please confirm your email
          description: Set the email alias to be used
        content:
          type: array
          items:
            type: object
            properties:
              mime_type:
                type: string
                format: mime type
                example: >-
                  "text/plain" / "text/html"
                description: Mime type of the associated value
              value:
                type: string
                example: "Hello"
                description: Content of the message to be sent
        categories:
          type: array
          items:
            type: string
            example: v3/email/user/account/mail/confirmation
          description: List of categories to be sent to sendgrid for tracking
        client:
          type: string
          example: v3
          description: Client of the service
        locale:
          type: string
          example: fr, fr_FR
          description: locale of the recipient
    ScenarioCreationRequest:
      type: object
      properties:
        template_key:
          type: string
          example: email/booking/passenger/trip/booked
          description: Set the template to be used for current notification
        context_data:
          type: object
          nullable: true
          additionalProperties:
            type: string
          example:
            price: 20
            currency: EUR
            vat: 4.25
            trips:
            - 6373836
            - 8738373
          description: >-
            Set context data of notification, these data will be used later on
            to populate the notification template, null if no data is needed
        recipient_uuid:
          type: string
          format: uuid
          example: 64e968f8-44d1-454c-a52c-80dc4794fbb0
          description: Set the blablacar recipient uuid
        expires_at_ts:
          type: integer
          format: timestamp
          example: 1539207074
          description: >-
            Set when notification will expire, for some reasons if the
            notification could not be sent, it will be considered as obsolete
            from a product perspective after the defined period of time, format
            is ISO8601 https://en.wikipedia.org/wiki/ISO_8601#Durations
    NotificationCheckResponse:
      type: object
      properties:
        allowed:
          type: boolean
          example: 'true'
    NotificationCreationResponse:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: fd341be6-b2bb-45c6-9128-eaad6d6c8581
    EmailCreationResponse:
      type: object
      properties:
        accepted:
          type: boolean
    Notification:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: fd341be6-b2bb-45c6-9128-eaad6d6c8581
          description: The unique identifier of the notification
        template_key:
          type: string
          example: email/booking/passenger/trip/booked
          description: The template key of notification
        channel:
          type: string
          nullable: true
          enum:
          - email
          - push
          - sms
          - viber
          example: email
          description: The channel of the notification
        recipient_uuid:
          type: string
          format: uuid
          nullable: true
          example: 64e968f8-44d1-454c-a52c-80dc4794fbb0
          description: The recipient unique identifier
        planned_at_ts:
          type: integer
          format: timestamp
          example: 1539207074
          description: The timestamp where the notification is planified to be sent
        sent_at:
          type: integer
          format: timestamp
          example: '1539207098'
          description: The timestamp where the notification has been sent by communication
          nullable: true
        delivered_at:
          type: integer
          format: timestamp
          example: '1539207098'
          description: >-
            The timestamp where the notification has been sent by the channel
            provider
          nullable: true
        acked_at:
          type: integer
          format: timestamp
          example: '1539207200'
          description: The timestamp where the notification has been seen by the end user
          nullable: true
        cancelled_at:
          type: integer
          nullable: true
          format: timestamp
          example: 'null'
          description: The timestamp where the notification has been cancelled