mirror of
https://github.com/jambonz/jambonz-api-server.git
synced 2025-12-19 05:47:46 +00:00
895 lines
26 KiB
YAML
895 lines
26 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: Jambones REST API
|
|
description: Jambones REST API
|
|
contact:
|
|
email: daveh@drachtio.org
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
version: 1.0.0
|
|
servers:
|
|
- url: /v1
|
|
description: development server
|
|
paths:
|
|
/ServiceProviders:
|
|
post:
|
|
summary: create service provider
|
|
operationId: createServiceProvider
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: service provider name
|
|
description:
|
|
type: string
|
|
required:
|
|
- name
|
|
responses:
|
|
201:
|
|
description: service provider successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- serviceProviderSid
|
|
properties:
|
|
serviceProviderSid:
|
|
type: string
|
|
format: uuid
|
|
example: 2531329f-fb09-4ef7-887e-84e648214436
|
|
400:
|
|
description: bad request
|
|
409:
|
|
description: an existing service provider already exists with this name
|
|
get:
|
|
summary: list service providers
|
|
operationId: listServiceProviders
|
|
responses:
|
|
200:
|
|
description: list of service providers
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ServiceProvider'
|
|
/ServiceProviders/{ServiceProviderSid}:
|
|
parameters:
|
|
- name: ServiceProviderSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
delete:
|
|
summary: delete a service provider
|
|
operationId: deleteServiceProvider
|
|
responses:
|
|
200:
|
|
description: service provider successfully deleted
|
|
404:
|
|
description: service provider not found
|
|
409:
|
|
description: service provider with active accounts can not be deleted
|
|
get:
|
|
summary: retrieve service provider
|
|
operationId: getServiceProvider
|
|
responses:
|
|
200:
|
|
description: service provider found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceProvider'
|
|
404:
|
|
description: service provider not found
|
|
put:
|
|
summary: update service provider
|
|
operationId: updateServiceProvider
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceProvider'
|
|
responses:
|
|
200:
|
|
description: service provider updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceProvider'
|
|
404:
|
|
description: service provider not found
|
|
/ServiceProviders/{ServiceProviderSid}/Accounts:
|
|
parameters:
|
|
- name: ServiceProviderSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
post:
|
|
summary: create an account
|
|
operationId: createAccount
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: account name
|
|
example: foobar
|
|
sipRealm:
|
|
type: string
|
|
description: sip realm for registration
|
|
example: sip.mycompany.com
|
|
registrationUrl:
|
|
type: string
|
|
format: url
|
|
description: authentication webhook for registration
|
|
example: https://mycompany.com
|
|
required:
|
|
- name
|
|
responses:
|
|
201:
|
|
description: account successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- accountSid
|
|
properties:
|
|
accountSid:
|
|
type: string
|
|
format: uuid
|
|
example: 2531329f-fb09-4ef7-887e-84e648214436
|
|
400:
|
|
description: bad request
|
|
409:
|
|
description: account with this name already exists
|
|
callbacks:
|
|
onRegistrationAttempt:
|
|
'{$request.body#/registrationUrl}/auth':
|
|
post:
|
|
requestBody:
|
|
description: |
|
|
provides details of the authentication request. The receiving server is responsible for authenticating the
|
|
request as per [RFC 2617](https://tools.ietf.org/html/rfc2617)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- method
|
|
- realm
|
|
- username
|
|
- expires
|
|
- nonce
|
|
- uri
|
|
- response
|
|
type: object
|
|
properties:
|
|
method:
|
|
type: string
|
|
description: sip request method
|
|
example: REGISTER
|
|
realm:
|
|
type: string
|
|
description: sip realm
|
|
example: mycompany.com
|
|
username:
|
|
type: string
|
|
description: sip username provided
|
|
example: daveh
|
|
expires:
|
|
type: number
|
|
description: expiration requested, in seconds
|
|
example: 3600
|
|
nonce:
|
|
type: string
|
|
description: nonce value
|
|
example: InFriVGWVoKeCckYrTx7wg=="
|
|
uri:
|
|
type: string
|
|
format: uri
|
|
description: sip uri in request
|
|
example: sip:mycompany.com
|
|
algorithm:
|
|
type: string
|
|
description: encryption algorithm used, default to MD5 if not provided
|
|
example: MD5
|
|
qop:
|
|
type: string
|
|
description: qop value
|
|
example: auth
|
|
cnonce:
|
|
type: string
|
|
description: cnonce value
|
|
example: 03d8d2aafd5a975f2b07dc90fe5f4100
|
|
nc:
|
|
type: string
|
|
description: nc value
|
|
example: 00000001
|
|
response:
|
|
type: string
|
|
description: digest value calculated by the client
|
|
example: db7b7dbec7edc0c427c1708031f67cc6
|
|
responses:
|
|
'200':
|
|
description: |
|
|
Your callback should return this HTTP status code in all cases.
|
|
if the request was authenticated and you wish to admit
|
|
the client to the network, this is indicated by setting the 'response'
|
|
attribute in the body to 'ok'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- response
|
|
properties:
|
|
response:
|
|
type: string
|
|
description: indicates whether the request was successfully authenticated
|
|
enum:
|
|
- ok
|
|
- failed
|
|
example: ok
|
|
message:
|
|
type: string
|
|
description: a human-readable message
|
|
example: authentication granted
|
|
expires:
|
|
type: number
|
|
description: |
|
|
The expires value to grant to the requesting user.
|
|
If not provided, the expires value in the request is observed.
|
|
If provided, must be less than the requested expires value.
|
|
exileDuration:
|
|
type: number
|
|
description: |
|
|
If provided, represents a period in seconds during which the source IP
|
|
address will be blacklisted by the platform.
|
|
|
|
get:
|
|
summary: list accounts for a service provider
|
|
operationId: listAccounts
|
|
responses:
|
|
200:
|
|
description: list of accounts
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Account'
|
|
/ServiceProviders/{ServiceProviderSid}/Accounts/{AccountSid}:
|
|
parameters:
|
|
- name: ServiceProviderSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
delete:
|
|
summary: delete an account
|
|
operationId: deleteAccount
|
|
responses:
|
|
200:
|
|
description: account successfully deleted
|
|
404:
|
|
description: account not found
|
|
409:
|
|
description: account with applications or phone numbers can not be deleted
|
|
|
|
/VoipCarriers:
|
|
post:
|
|
summary: create voip carrier
|
|
operationId: createVoipCarrier
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: voip carrier name
|
|
description:
|
|
type: string
|
|
required:
|
|
- name
|
|
responses:
|
|
201:
|
|
description: voip carrier successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- voipCarrierSid
|
|
properties:
|
|
accountSid:
|
|
type: string
|
|
format: uuid
|
|
example: 2531329f-fb09-4ef7-887e-84e648214436
|
|
400:
|
|
description: bad request
|
|
409:
|
|
description: an existing voip carrier already exists with this name
|
|
get:
|
|
summary: list voip carriers
|
|
operationId: listVoipCarriers
|
|
responses:
|
|
200:
|
|
description: list of voip carriers
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/VoipCarrier'
|
|
/VoipCarriers/{VoipCarrierSid}:
|
|
parameters:
|
|
- name: VoipCarrierSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
delete:
|
|
summary: delete a voip carrier
|
|
operationId: deleteVoipCarrier
|
|
responses:
|
|
200:
|
|
description: voip carrier successfully deleted
|
|
404:
|
|
description: voip carrier not found
|
|
409:
|
|
description: voip carrier with active phone numbers can not be deleted
|
|
get:
|
|
summary: retrieve voip carrier
|
|
operationId: getVoipCarrier
|
|
responses:
|
|
200:
|
|
description: voip carrier found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VoipCarrier'
|
|
404:
|
|
description: voip carrier not found
|
|
put:
|
|
summary: update voip carrier
|
|
operationId: updateVoipCarrier
|
|
parameters:
|
|
- name: VoipCarrierSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VoipCarrier'
|
|
responses:
|
|
200:
|
|
description: voip carrier updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VoipCarrier'
|
|
404:
|
|
description: voip carrier not found
|
|
/VoipCarriers/{VoipCarrierSid}/PhoneNumbers:
|
|
parameters:
|
|
- name: VoipCarrierSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
post:
|
|
summary: provision a phone number into inventory from a Voip Carrier
|
|
operationId: provisionPhoneNumber
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
number:
|
|
type: string
|
|
description: telephone number
|
|
description:
|
|
type: string
|
|
required:
|
|
- number
|
|
responses:
|
|
201:
|
|
description: phone number successfully provisioned into inventory
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- phoneNumberSid
|
|
properties:
|
|
phoneNumberSid:
|
|
type: string
|
|
format: uuid
|
|
example: 2531329f-fb09-4ef7-887e-84e648214436
|
|
400:
|
|
description: bad request
|
|
409:
|
|
description: the specified phone number already exists in inventory
|
|
get:
|
|
summary: list phone numbers for a carrier
|
|
operationId: listProvisionedPhoneNumbers
|
|
responses:
|
|
200:
|
|
description: list of phone numbers
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PhoneNumber'
|
|
|
|
/Accounts/{AccountSid}/Applications:
|
|
post:
|
|
summary: create application
|
|
operationId: createApplication
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: application name
|
|
description:
|
|
type: string
|
|
statusUrl:
|
|
type: string
|
|
format: url
|
|
description: webhook to pass call status updates to
|
|
voiceUrl:
|
|
type: string
|
|
format: url
|
|
description: webhook to call when call is received
|
|
voiceFallbackUrl:
|
|
type: string
|
|
format: url
|
|
description: fallback webook url
|
|
required:
|
|
- name
|
|
- statusUrl
|
|
- voiceUrl
|
|
responses:
|
|
201:
|
|
description: application successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- ApplicationSid
|
|
properties:
|
|
accountSid:
|
|
type: string
|
|
format: uuid
|
|
example: 2531329f-fb09-4ef7-887e-84e648214436
|
|
400:
|
|
description: bad request
|
|
409:
|
|
description: an existing application already exists with this name
|
|
get:
|
|
summary: list applications for an account
|
|
operationId: listApplications
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: retrieve applications for the account
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Application'
|
|
/Accounts/{AccountSid}/Applications/{ApplicationSid}:
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
- name: ApplicationSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
delete:
|
|
summary: delete an application
|
|
operationId: deleteApplication
|
|
responses:
|
|
200:
|
|
description: application successfully deleted
|
|
404:
|
|
description: application not found
|
|
get:
|
|
summary: retrieve application
|
|
operationId: getApplication
|
|
responses:
|
|
200:
|
|
description: application found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Application'
|
|
404:
|
|
description: application not found
|
|
put:
|
|
summary: update application
|
|
operationId: updateApplication
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
- name: ApplicationSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Application'
|
|
responses:
|
|
200:
|
|
description: application updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Application'
|
|
404:
|
|
description: application not found
|
|
/Accounts/{AccountSid}/Applications/{ApplicationSid}/PhoneNumbers/{PhoneNumberSid}:
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: ApplicationSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: PhoneNumberSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
delete:
|
|
summary: remove a phone number from an application
|
|
operationId: removePhoneNumberFromApplication
|
|
responses:
|
|
200:
|
|
description: phone number removed from this application
|
|
404:
|
|
description: phone number not found or was not assigned to this application
|
|
put:
|
|
summary: provision a phone number for an Application
|
|
operationId: assignPhoneNumberToApplication
|
|
responses:
|
|
200:
|
|
description: phone number successfully assigned to application
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PhoneNumber'
|
|
400:
|
|
description: bad request
|
|
409:
|
|
description: the specified phone number is already assigned to another application or account
|
|
|
|
/Accounts/{AccountSid}/Apikeys:
|
|
post:
|
|
summary: create api key
|
|
operationId: createApikey
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
responses:
|
|
201:
|
|
description: api key successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- apiKey
|
|
- apiKeySid
|
|
properties:
|
|
apiKeySid:
|
|
type: string
|
|
description: system identifier for api key that was created
|
|
format: uuid
|
|
example: 7531328e-eb08-4eff-887e-84e648214872
|
|
apiKey:
|
|
type: string
|
|
description: api key
|
|
format: uuid
|
|
example: 2531329f-fb09-4ef7-887e-84e648214436
|
|
404:
|
|
description: Account not found
|
|
/Accounts/{AccountSid}/Apikeys/{ApiKeySid}:
|
|
delete:
|
|
summary: delete api key
|
|
operationId: deleteApiKey
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
style: simple
|
|
explode: false
|
|
schema:
|
|
type: string
|
|
- name: ApiKeySid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: api key deleted
|
|
404:
|
|
description: api key or account not found
|
|
|
|
/Accounts/{AccountSid}/Applications/{ApplicationSid}/Calls:
|
|
post:
|
|
summary: create a call
|
|
operationId: createCall
|
|
parameters:
|
|
- name: AccountSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: ApplicationSid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- from
|
|
- to
|
|
type: object
|
|
properties:
|
|
url:
|
|
type: string
|
|
description: |
|
|
The url of the web application to control this call.
|
|
If not provided, the url specified in the application will be used
|
|
example: https://mycompany.com/deliver-message.json
|
|
from:
|
|
type: string
|
|
description: The calling party number
|
|
example: 16172375089
|
|
to:
|
|
type: string
|
|
description: The telephone number or sip endpoint to call
|
|
example: 16172228000
|
|
recordingUrl:
|
|
type: string
|
|
format: url
|
|
description: A websocket url to stream the call audio to
|
|
example: wss://myserver.com
|
|
recordingMix:
|
|
type: string
|
|
description: whether to record either or both parties
|
|
enum:
|
|
- caller
|
|
- callee
|
|
- stereo
|
|
- mixed
|
|
example: stereo
|
|
statusCallback:
|
|
type: string
|
|
format: url
|
|
description: The url to send call status change events to
|
|
example: https://company.com/status
|
|
responses:
|
|
201:
|
|
description: call successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- callSid
|
|
properties:
|
|
callSid:
|
|
type: string
|
|
format: uuid
|
|
example: 2531329f-fb09-4ef7-887e-84e648214436
|
|
400:
|
|
description: bad request
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: token
|
|
schemas:
|
|
ServiceProvider:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
name:
|
|
type: string
|
|
description:
|
|
type: string
|
|
VoipCarrier:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
name:
|
|
type: string
|
|
description:
|
|
type: string
|
|
Account:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
sipRealm:
|
|
type: string
|
|
registrationHook:
|
|
type: string
|
|
format: url
|
|
serviceProvider:
|
|
$ref: '#/components/schemas/ServiceProvider'
|
|
Application:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
name:
|
|
type: string
|
|
account:
|
|
$ref: '#/components/schemas/Account'
|
|
callHook:
|
|
type: string
|
|
format: url
|
|
callBackupHook:
|
|
type: string
|
|
format: url
|
|
callStatusChangeHook:
|
|
type: string
|
|
format: url
|
|
PhoneNumber:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
number:
|
|
type: string
|
|
voipCarrier:
|
|
$ref: '#/components/schemas/VoipCarrier'
|
|
account:
|
|
$ref: '#/components/schemas/Account'
|
|
application:
|
|
$ref: '#/components/schemas/Application'
|
|
RegisteredUser:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
username:
|
|
type: string
|
|
domain:
|
|
type: string
|
|
Call:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
application:
|
|
$ref: '#/components/schemas/Application'
|
|
parentCall:
|
|
$ref: '#/components/schemas/Call'
|
|
direction:
|
|
type: string
|
|
enum:
|
|
- inbound
|
|
- outbound
|
|
phoneNumber:
|
|
$ref: '#/components/schemas/PhoneNumber'
|
|
inboundUser:
|
|
$ref: '#/components/schemas/RegisteredUser'
|
|
outboundUser:
|
|
$ref: '#/components/schemas/RegisteredUser'
|
|
callingNumber:
|
|
type: string
|
|
calledNumber:
|
|
type: string
|
|
|
|
security:
|
|
- bearerAuth: [] |