From 0e437cf729dd82226a9d0145bd8a7296e33919a7 Mon Sep 17 00:00:00 2001 From: Anthony Gauchy Date: Fri, 5 May 2023 19:27:15 +0200 Subject: [PATCH] Epic FLEXIAPI-38 Adding Flexisip stats api OpenApi specification Add endpoint to handle BYEs. The proxy would have a hard time finding the device ID when forwarding a BYE. To fix that, we moved the `terminated` state to the call object itself, which makes more sense anyway since a call can only be established with a single device. Device subobjects now only store the final state of the initial invite. Remove format restriction on Call IDs -> They can be any string, not just UUIDs. Fix typos --- flexiapi/openapi-spec/flexisip-stats.yaml | 542 ++++++++++++++++++++++ 1 file changed, 542 insertions(+) create mode 100644 flexiapi/openapi-spec/flexisip-stats.yaml diff --git a/flexiapi/openapi-spec/flexisip-stats.yaml b/flexiapi/openapi-spec/flexisip-stats.yaml new file mode 100644 index 0000000..8065f7d --- /dev/null +++ b/flexiapi/openapi-spec/flexisip-stats.yaml @@ -0,0 +1,542 @@ +openapi: 3.0.3 +servers: + - url: api/stats +info: + description: |- + API used to publish stats from a Flexisip server. + version: 1.0.0 + title: Flexiapi Flexisip stats + license: + name: GNU GPL + url: 'https://www.gnu.org/licenses/licenses.en.html' +tags: + - name: messages + description: Everything about messages + - name: calls + description: Everything about calls + - name: conferences + description: Everything about conferences +paths: + + ##################################################################################### + ############################# message ############################################### + ##################################################################################### + /messages: + post: + tags: + - messages + summary: Add information about a new message + description: Add information about a new message + operationId: addMessage + responses: + '200': + description: Successful operation + '422': + description: Invalid input + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + /messages/{message_id}/to/{sip_uri}/devices/{device_id}: + patch: + tags: + - messages + summary: Notify a message state update for a recipient device. + description: Notify a message state update for a recipient device. + operationId: notifyMessageDeviceResponse + parameters: + - name: message_id + in: path + description: ID of message to patch + required: true + schema: + type: string + - name: sip_uri + in: path + description: SIP address of the recipient + required: true + schema: + type: string + - name: device_id + in: path + description: Device id of recipient, might be an url if no ID exist. + required: true + schema: + type: string + responses: + '200': + description: Successful operation + '400': + description: Invalid message_id/to/device_id supplied + '404': + description: Message/To not found + '422': + description: Validation exception + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/MessageDeviceResponse' + + ##################################################################################### + ############################# call ################################################## + ##################################################################################### + /calls: + post: + tags: + - calls + summary: Add information about a new call + description: Add information about a new call + operationId: addCall + responses: + '200': + description: Successful operation + '422': + description: Invalid input + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Call' + /calls/{call_id}/devices/{device_id}: + patch: + tags: + - calls + summary: Update call on status update (ringing, accepted...), by device. + operationId: updateCallDeviceState + parameters: + - name: call_id + in: path + description: ID of call to patch + required: true + schema: + type: string + - name: device_id + in: path + description: Device id of recipient, might be an url if no ID exist. + required: true + schema: + type: string + responses: + '200': + description: Successful operation + '400': + description: Invalid call_id/device_id supplied + '404': + description: Call not found + '422': + description: Validation exception + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CallDeviceState' + /calls/{call_id}: + patch: + tags: + - calls + summary: Update call on BYE. + operationId: updateCallState + parameters: + - name: call_id + in: path + description: ID of call to patch + required: true + schema: + type: string + responses: + '200': + description: Successful operation + '400': + description: Invalid call_id supplied + '404': + description: Call not found + '422': + description: Validation exception + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + required: + - ended_at + properties: + ended_at: + type: string + format: date-time + example: 2017-07-21T19:42:26Z + + ##################################################################################### + ############################# conference ############################################ + ##################################################################################### + /conferences: + post: + tags: + - conferences + summary: Add information about a new conference + description: Add information about a new conference + operationId: addConference + responses: + '200': + description: Successful operation + '422': + description: Invalid input + security: + - api_key: [] + requestBody: + description: Create a new call + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Conference' + /conferences/{conference_id}: + patch: + tags: + - conferences + summary: Notify that a conference ended + operationId: notifyConferenceEnded + parameters: + - name: conference_id + in: path + description: ID of conference to patch + required: true + schema: + type: string + responses: + '200': + description: Successful operation + '400': + description: Invalid conference_id supplied + '404': + description: Conference not found + '422': + description: Validation exception + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ended_at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + /conferences/{conference_id}/participants/{sip_uri}/events: + post: + tags: + - conferences + summary: Notify a participant event + operationId: conferenceAddParticipantEvent + parameters: + - name: conference_id + in: path + description: ID of conference to patch + required: true + schema: + type: string + - name: sip_uri + in: path + description: SIP address of the participant + required: true + schema: + type: string + responses: + '200': + description: Successful operation + '400': + description: Invalid conference_id supplied + '404': + description: Conference not found + '422': + description: Validation exception + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ParticipantEvent' + /conferences/{conference_id}/participants/{sip_uri}/devices/{device_id}/events: + post: + tags: + - conferences + summary: Notify a participant device event + operationId: conferenceAddParticipantDeviceEvent + parameters: + - name: conference_id + in: path + description: ID of conference to patch + required: true + schema: + type: string + - name: sip_uri + in: path + description: SIP address of the participant + required: true + schema: + type: string + - name: device_id + in: path + description: Device uuid + required: true + schema: + type: string + responses: + '200': + description: Successful operation + '400': + description: Invalid conference_id supplied + '404': + description: Conference not found + '422': + description: Validation exception + security: + - api_key: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ParticipantDeviceEvent' + +##################################################################################### +############################# components ############################################ +##################################################################################### +components: + schemas: + ############################# message ############################################### + MessageDevices: + type: object + additionalProperties: + $ref: '#/components/schemas/MessageDeviceResponse' + example: + device_id_1: + last_status: 200 + received_at: "2017-07-21T17:32:28Z" + device_id_2: + last_status: 408 + received_at: "2017-07-21T17:32:28Z" + device_id_3: null + + MessageDeviceResponse: + nullable: true + required: + - last_status + - received_at + properties: + last_status: + type: number + example: 200 + received_at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + + Message: + required: + - id + - from + - to + - sent_at + - encrypted + properties: + id: + type: string + format: uuid + example: 84c937d1-f1b5-475d-adb7-b41b78b078d4 + from: + type: string + format: sip-address + example: user@sip.linphone.org + to: + type: object + additionalProperties: + $ref: '#/components/schemas/MessageDevices' + example : + user1@domain.org: + device_id_1: + last_status: 200 + received_at: "2017-07-21T17:32:28Z" + device_id_2: + last_status: 408 + received_at: "2017-07-21T17:32:28Z" + device_id_3: null + user2@domain.org: + device_id_1: + last_status: 503 + received_at: "2017-07-21T17:32:28Z" + device_id_2: null + sent_at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + encrypted: + type: boolean + conference_id: + type: string + nullable: true + example: iHVDMq6MxSKp60bT + + ############################# call ############################################### + Terminated: + required: + - at + - state + properties: + at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + state: + type: string + description: Call status + enum: + - error + - declined + - canceled + - accepted_elsewhere + - declined_elsewhere + - accepted + + CallDevices: + type: object + additionalProperties: + $ref: '#/components/schemas/CallDeviceState' + example: + device_id_1: + rang_at: 2017-07-21T17:32:28Z + invite_terminated: + at: 2017-07-21T18:32:28Z + state: accepted + device_id_2: + rang_at: 2017-07-21T17:32:28Z + invite_terminated: + at: 2017-07-21T18:32:28Z + state: accepted_elsewhere + device_id_3: null + + CallDeviceState: + nullable: true + properties: + rang_at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + invite_terminated: + $ref: '#/components/schemas/Terminated' + + Call: + required: + - id + - from + - to + - initiated_at + properties: + id: + type: string + example: 4722b0233fd8cafad3cdcafe5510fe57 + from: + type: string + format: sip-address + example: user@sip.linphone.org + to: + type: string + format: sip-address + example: user@sip.linphone.org + devices: + $ref: '#/components/schemas/CallDevices' + initiated_at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + ended_at: + type: string + nullable: true + format: date-time + example: 2017-07-21T19:42:26Z + conference_id: + type: string + nullable: true + example: iHVDMq6MxSKp60bT + + ############################# conference ############################################### + Conference: + required: + - id + - created_at + properties: + id: + type: string + example: iHVDMq6MxSKp60bT + created_at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + ended_at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + schedule: + type: string + + ParticipantEvent: + required: + - type + - at + properties: + type: + type: string + description: Participant event type + enum: + - added + - left + - removed + at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + + ParticipantDeviceEvent: + required: + - type + - at + properties: + type: + type: string + description: Participant event type + enum: + - invited + - joined + - left + - error + at: + type: string + format: date-time + example: 2017-07-21T17:32:28Z + + ############################# securitySchemes ############################################### + securitySchemes: + api_key: + type: apiKey + name: x-api-key + in: header