generated from camaraproject/Template_API_Repository
-
Notifications
You must be signed in to change notification settings - Fork 28
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add generic notification OAS file #41
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,253 @@ | ||
openapi: 3.0.3 | ||
info: | ||
title: Event Notification | ||
description: | | ||
The event notification endpoint is used by the API server to notify the API consumer that an event occured. The notification is the message posted on listener side. | ||
|
||
# Introduction | ||
|
||
A lot of CAMARA APIs offer the capability to consumer to receive event notification. | ||
Event notification are defined in each API definition but in order to provide consistency accross CAMARA API a common event notification strucutre is provided. | ||
|
||
# Relevant terms and definitions | ||
|
||
* **eventType** : Type of event as defined in each CAMARA API (examples: ROAMING_STATUS, QOS_STATUS_CHANGED, PAYMENT_COMPLETED, etc...) | ||
|
||
* **eventDetail** : Event details structure depending on the eventType and defined in each CAMARA API. | ||
|
||
# API Functionality | ||
|
||
|
||
Only one endpoint/operation is provided: `POST /notifications` | ||
|
||
This endpoint describes the event notification received on subscription listener side when the event occurred. A detailed description of the event notification is provided in the CAMARA API design guideline document. | ||
|
||
|
||
|
||
termsOfService: http://swagger.io/terms/ | ||
contact: | ||
email: project-email@sample.com | ||
license: | ||
name: Apache 2.0 | ||
url: https://www.apache.org/licenses/LICENSE-2.0.html | ||
version: 0.5.0-wip | ||
externalDocs: | ||
description: Product documentation at CAMARA | ||
url: https://github.com/camaraproject/ | ||
security: | ||
# - {} | ||
- oAuth2ClientCredentials: [] | ||
# - BasicAuth: [] | ||
# - apiKey: [] | ||
servers: | ||
- url: '{apiRoot}/{basePath}' | ||
variables: | ||
apiRoot: | ||
default: http://localhost:9091 | ||
description: API root | ||
basePath: | ||
default: /event-notification/v0 | ||
description: Base path for the event notifiation API | ||
tags: | ||
- name: Event Notification | ||
description: | | ||
Notification received on subscription listener side. | ||
paths: | ||
/eventNotifications: | ||
post: | ||
tags: | ||
- Event Notification | ||
summary: "Notification endpoint to notify listener that an event had occurred" | ||
description: Notification endpoint to notify listener that an event occurred. This endpoint must be exposed on the listener side. | ||
operationId: postNotification | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. maybe rename to "sendNotification" There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done 😄 in #43 |
||
requestBody: | ||
required: true | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/EventNotification" | ||
examples: | ||
EVENT_EXEMPLE: | ||
$ref: '#/components/examples/EVENT_EXEMPLE' | ||
|
||
responses: | ||
204: | ||
description: No Content | ||
400: | ||
$ref: "#/components/responses/Generic400" | ||
401: | ||
$ref: "#/components/responses/Generic401" | ||
403: | ||
$ref: "#/components/responses/Generic403" | ||
500: | ||
description: Server error | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
503: | ||
$ref: "#/components/responses/Generic503" | ||
components: | ||
securitySchemes: | ||
oAuth2ClientCredentials: | ||
type: oauth2 | ||
flows: | ||
clientCredentials: | ||
tokenUrl: '{tokenUrl}' | ||
scopes: {} | ||
# BasicAuth: | ||
# type: http | ||
# scheme: basic | ||
# apiKey: | ||
# type: apiKey | ||
# description: API key to authorize requests | ||
# name: apikey | ||
# in: query | ||
three_legged: | ||
type: oauth2 | ||
flows: | ||
authorizationCode: | ||
authorizationUrl: https://auth.example.com/authorize | ||
tokenUrl: https://auth.example.com/token | ||
scopes: | ||
device-status-roaming-read: Read device roaming status | ||
schemas: | ||
ErrorInfo: | ||
type: object | ||
required: | ||
- status | ||
- code | ||
- message | ||
properties: | ||
status: | ||
type: integer | ||
description: HTTP response status code | ||
code: | ||
type: string | ||
description: Code given to this error | ||
message: | ||
type: string | ||
description: Detailed error description | ||
|
||
|
||
EventSubscriptionId: | ||
type: string | ||
description: The event subscription identifier. | ||
|
||
EventTime: | ||
format: date-time | ||
type: string | ||
description: The time when the event was notified. | ||
|
||
EventNotification: | ||
description: The notification callback. | ||
type: object | ||
required: | ||
- event | ||
properties: | ||
eventSubscriptionId: | ||
$ref: '#/components/schemas/EventSubscriptionId' | ||
event: | ||
$ref: '#/components/schemas/Event' | ||
|
||
Event: | ||
description: Generic event structure | ||
required: | ||
- eventType | ||
- eventTime | ||
- eventDetail | ||
properties: | ||
eventType: | ||
type: string | ||
eventTime: | ||
$ref: '#/components/schemas/EventTime' | ||
eventId: | ||
type: string | ||
format: uuid | ||
eventDetail: | ||
type: object | ||
discriminator: | ||
propertyName: 'eventType' | ||
|
||
|
||
responses: | ||
Generic400: | ||
description: Problem with the client request | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
example: | ||
status: 400 | ||
code: "INVALID_ARGUMENT" | ||
message: "Client specified an invalid argument, request body or query param" | ||
Generic401: | ||
description: Authentication problem with the client request | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
example: | ||
status: 401 | ||
code: "UNAUTHENTICATED" | ||
message: "Request not authenticated due to missing, invalid, or expired credentials" | ||
Generic403: | ||
description: Client does not have sufficient permission | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
example: | ||
status: 403 | ||
code: "PERMISSION_DENIED" | ||
message: "Client does not have sufficient permissions to perform this action" | ||
Generic404: | ||
description: Resource Not Found | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
example: | ||
code: NOT_FOUND | ||
message: "The specified resource is not found" | ||
Generic409: | ||
description: Conflict | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
example: | ||
code: CONFLICT | ||
message: "The specified resource is in a conflict" | ||
Generic500: | ||
description: Server error | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
example: | ||
status: 500 | ||
code: "INTERNAL" | ||
message: "Server error" | ||
Generic503: | ||
description: Service unavailable. Typically the server is down. | ||
content: | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/ErrorInfo" | ||
example: | ||
status: 503 | ||
code: "UNAVAILABLE" | ||
message: "Service unavailable" | ||
examples: | ||
EVENT_EXEMPLE: | ||
value: | ||
eventSubscriptionId: 123654 | ||
event: | ||
eventType: EVENT_TYPE_AS_DEFINED_IN_EACH_API | ||
eventTime: 2023-01-17T13:18:23.682Z | ||
eventDetail: | ||
eventDetailAttribute1: | ||
eventDetailAttribute2: 123456789 | ||
eventDetailAttribute3: true | ||
eventDetailAttribute4: .... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This endpoint is the one indicated vía {$request.body#/webhook/notificationUrl}.
Then, it is not really required to append "/eventNotifications"
So maybe we can agree on indicating like:
/{$request.body#/webhook/notificationUrl}
And in the description comment:
INFORMATIVE ENDPOINT. The value of this endpoint is freely declared by each client app by means of resource-based subscription or instance-based subscription. /{$request.body#/webhook/notificationUrl} is just a convention naming referring to an absolute URL, indeed the one indicated by API client in the triggering of the procedure (resource-based or instance-based).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @PedroDiez,
Thanks for your comments.
As this is a generic OAS, we can't refer to {$request.body#/webhook/notificationUrl} that doesn't exists in this context, I'll replace it by /your_webhook_notificationUrl and include your description in #43
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @patrice-conil
Have seen the update in PR#43, I think it would apply in the same fashion in this PR, isn't?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @PedroDiez,
yes, but I'm waiting for a decision before reporting in this PR.