Skip to content

Instantly share code, notes, and snippets.

@Diwann

Diwann/spec.yml

Created Oct 10, 2019
Embed
What would you like to do?
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.