Skip to content

Instantly share code, notes, and snippets.

@bver

bver/both.yaml

Last active May 22, 2017 08:03
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save bver/5219d7a74e2edf26a476777b124d001f to your computer and use it in GitHub Desktop.
Save bver/5219d7a74e2edf26a476777b124d001f to your computer and use it in GitHub Desktop.
Download ZIP
trying redoc
Raw
both.yaml
### GENERATED FILE. DO NOT EDIT THIS FILE, EDIT src/*.m4.yaml FILES INSTEAD ###
swagger: '2.0'
info:
title: Ytica API
description: |
Ytica API consists of two services: Identity and Speech Analytics.
Currently, Speech Analytics Services provides basic recording statistics and phrase spotting for a single audio recording.
version: draft
schemes:
- https
x-tagGroups:
- name: Identity Service
tags:
- Authorization Token
- name: Speech Analytics Service
tags:
- Speech Jobs
- Job Results
securityDefinitions:
Bearer:
type: apiKey
name: Authorization
in: header
description: |
For accessing the API a valid JWT token must be passed in the 'Authorization' header.
A JWT token is generated by the Identity Service and is valid for a limited time period.
The following syntax must be used in the 'Authorization' header :
Bearer: xxxxxx.yyyyyyy.zzzzzz
where xxxxxx.yyyyyyy.zzzzzz is the issued JWT token
x-example: 'Bearer: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ'
paths:
# {{ m4 preprocessor
"/identity/authorizations":
x-summary: Authorizing Identity Service
x-description: |
Endpoint for user authorizations.
post:
tags:
- Authorization Token
summary: Provides the new authorization token for the use in all Ytica API services.
description: |
This operation authorizes the API user for all Ytica API services.
The API secret token was given to the user to authenticate her for API operations. It's main purpose is to
establish the user's identity in the context of Ytica API services.
The API secret token has not restricted validity so the user is responsible for keeping it safe and must
guarantee it cannot leak outside user's application.
For performance and security reasons the API secret token cannot be used directly for accessing executive API
operations. Instead, the user has to ask for authorization first using this POST.
The authorization process simply takes the API secret token and generates the authorization token with
the time-restricted validity. This authorization token is self-contained and (currently) respects RFC 7519
standard.
It can be repeatedly used in executive API operations untill it expires. The expiration time can be parsed from
the token however for the user convenience it is returned in the response in a human readable form of ISO 8601
Extended Format. The user should ask for another authorization token sufficiently in advance.
Each call of this operation generates a new authorization token with a new expiration time so it is possible to
get a new one soon after its generation. However too frequent regeneration leads to performance loses and is
discouraged.
The best practice is to respect the expiration time and schedule re-generation according it, obviously with
some time buffer covering the call latence. Asking for a new authorization token right before each executive
API operation is an antipattern.
consumes:
- application/json
produces:
- application/json
parameters:
-
name: body
in: body
description: JSON containing the API secret token
required: true
schema:
$ref: '#/definitions/AuthorizationRequest'
responses:
200:
description: Generates the authorization token with the time restriction.
headers:
Content-type:
type: string
description: application/json
schema:
$ref: '#/definitions/AuthorizationResponse'
400:
description: Unexpected error
headers:
Content-type:
type: string
description: application/problem+json
schema:
$ref: '#/definitions/ProblemDetail'
403:
description: Authorization error
headers:
Content-type:
type: string
description: application/problem+json
schema:
$ref: '#/definitions/ProblemDetailAuth'
"/speech/jobs":
x-summary: Speech Analytic Jobs
x-description: |
All speech analytics jobs are asynchronous since the time between http request and response is often not
sufficient for the job to be completed. Therefore task definitions are accepted by a single API call and results are sent back to the user defined callback when ready.
post:
tags:
- Speech Jobs
summary: Create a new composite analytic job
description: |
Starts an analytic job as a composite request consisting of several tasks:
- Statistics (optional)
- Search for Phrases (optional)
- Transcripts (in the future)
At least one _task_ has to be specified.
### Statistics
Basic statistics are:
- Total length of the audio
- Cummulative cross-talk time
- Mutual silence time
- Talk times per channel
All stats are reported in seconds.
Stats are computed when
statistics: {}
key is present in the _tasks_ attribute.
### Phrases
This _embedded resource _phrase_set_ defines a set or list of text phrases in a specific
language we want to look for.
The _min_confidence_ parameter specifies the minimal confidence enabling to set the confidence
threshold. Phrase findings with the confidence lower than the confidence thresholds are not
reported which helps to reduce the number of false alarms at the speech engine level.
There are two ways how to specify the phrase set:
- Phrase List .. simple array of all phrases
- Phrases Object .. with the minimal confidence specified for each phrase.
### Recording
There is a link in the job definition which specifies the audio URL.
The audio URL must be accessible to the Speech Service. It might contain an opaque hash as
a mean of a basic trust between consumer and the Speech Service.
Recording represents the way the Speech API knows audio data.
The supported audio format is:
8kHz stereo WAV (both 16bit PCM and A-law)
We may support different formats and different transport strategies in the future.
Mono WAVs are also tolerated, however one channel per speaker condition is required i.e. mixing
speakers in mono channels is not allowed. A single recording can store a conversation consisting
one or more channels. Typically, the Recording is the stereo WAV where two speakers talk to each
other, each speaker has a separate channel. However, a single recording (a single conversation)
can be recorded in more WAVs with different offsets for channels. The only requirement is that
a speech of more speakers must not mix in a single channel.
#### Result Callback
The client has to provide _links with the results_callback.
Again, the URL can be opaque as in the case of recording audio.
Please note that there are no exact guarantees w.r.t. the time between the job creation and
sending back results.
security:
- Bearer: []
consumes:
- application/hal+json
produces:
- application/hal+json
parameters:
-
name: body
in: body
description: HAL (JSON) describing the analytic job.
required: true
schema:
$ref: '#/definitions/JobDescription'
responses:
202:
description: Accepted the new asynchronous job
headers:
Content-type:
type: string
description: application/hal+json
schema:
$ref: '#/definitions/JobAccepted'
400:
description: Unexpected error
headers:
Content-type:
type: string
description: application/problem+json
schema:
$ref: '#/definitions/ProblemDetail'
403:
description: Authorization error
headers:
Content-type:
type: string
description: application/problem+json
schema:
$ref: '#/definitions/ProblemDetailAuth'
"/any/path/to/consumer/provided/endpoint":
x-summary: Callback Receiving Endpoint
x-description: |
The client's endpoint is called with the URL provided by _links with the results_callback specified
by Job Creation operation.
post:
tags:
- Job Results
summary: Receive results
description: |
Inform Ytica API consumer about the results of asynchronous job by calling the endpoint.
The endpoint URL must be accessible to the Speech Service and defined in _links section of
the Job Creation operation.
The client is informed about the job outcome (completed/failed).
All specified tasks have their according tasks_result.
consumes:
- application/json
produces:
- application/json
parameters:
-
name: body
in: body
description: JSON describing the result.
required: true
schema:
$ref: '#/definitions/CallbackRequest'
responses:
200:
description: Consumer informs the Speech Service that succesfuly received results.
headers:
Content-type:
type: string
description: application/hal+json
schema:
$ref: '#/definitions/CallbackResponse'
400:
description: Unexpected error
headers:
Content-type:
type: string
description: application/problem+json
schema:
$ref: '#/definitions/ProblemDetail'
# }} m4 preprocessor
definitions:
# {{ m4 preprocessor
AuthorizationRequest:
title: The API secret token authenticating the user
description: |
The secret information proving the user's identity in the context of Ytica API services.
type: object
properties:
api_secret_token:
type: string
description: Authentication API Secret Token which proves the API consumer identity.
required:
- api_secret_token
example:
api_secret_token: '89281f03-7e0e-4e50-b06f-e1e5393aef76'
AuthorizationResponse:
title: The authorization of the user
description: |
Authorization token and expiration information.
properties:
authorization_token:
type: string
description: The self-contained authorization token.
expire:
type: string
description: Token expiration time respecting ISO 8601.
required:
- authorization_token
- expire
example:
authorization_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ'
expire: '2017-05-09T11:00:55.712Z'
JobDescription:
title: The composite speech analytic job.
description: |
The resource representing the asynchronous speech analytic job consisting of several tasks.
Any task binds a recording with any of:
- simple statistics
- phrase search
- transcripts (in the future).
Results are available via results_callback.
type: object
properties:
_links:
type: object
properties:
results_callback:
description: |
Callback is triigerred by the Speech service when job results are ready.
In the rare case of a failed job the callback is called with the content-type problem+json.
type: object
properties:
href:
type: string
format: url
required:
- href
recording_audio:
description: The accessible location of the audio recording.
type: object
properties:
href:
type: string
format: url
required:
- href
required:
- results_callback
- recording_audio
_embedded:
type: object
properties:
phrase_set:
$ref: '#/definitions/PhraseSet'
tasks:
type: object
description: |
Tasks parameters define parts of the job. If the key is omitted the task will not be processed.
At least one of
- statistics
- phrase_spotting
must be present.
properties:
statistics:
type: object
description: Ask for simple recording statistics to be computed.
phrase_spotting:
type: object
description: If the phrase_spotting task is specified the _embedded must contain the phrase_set.
properties:
min_confidence:
type: number
format: float
minimum: 20.0
description: Minimum confidence threshold allowing filtration (default for all phrases in PhraseSet).
# anyOf:
# - statistics
# - phrase_spotting
required:
- _links
- tasks
example:
_links:
results_callback:
href: 'http://example.com/results_endpoint/4354235_34_3255'
recording_audio:
href: 'http://example.com/external_storage/42/recordings/4354235_34.wav'
_embedded:
phrase_set:
phrase_list:
- hello
- how are you
language: en-US
tasks:
statistics: {}
phrase_spotting:
min_confidence: 30.0
PhraseSet:
title: Phrase Set
description: |
This is the set of phrases to be searched in audio files.
There are two ways of defining phrases: Using
- phrase_list .. a simple array of phrase texts
- phrases .. an array of phrase objects for an individual control of the minimal confidence threshold.
type: object
properties:
phrase_list:
type: array
items:
type: string
description: Phrase texts
phrases:
type: array
items:
type: object
properties:
text:
type: string
description: Phrase text
min_confidence:
type: number
format: float
minimum: 20.0
description: Minimal confidence threshold for a particular phrase
required:
- text
language:
type: string
description: |
Language of the Phrase set (e.g. en-US).
See https://tools.ietf.org/html/rfc5646 or http://www.lingoes.net/en/translator/langcode.htm
required:
- language
# anyOf:
# - phrase_list
# - phrases
example:
phrase_list:
- hello
- how are you
language: en-US
ResultsStatistics:
title: Results of the statistics task
description: Simple cummulative information about speech/silence parts th the recording in audio channels.
type: object
properties:
total_length:
type: number
format: float
description: Total duration of the call (in seconds)
cross_talk:
type: number
format: float
description: Total duration of crosstalks (in seconds)
cross_silence:
type: number
format: float
description: Total duration of silence in all channels (in seconds)
talk_times:
type: array
items:
type: number
format: float
description: |
Cummulative duration of talk parts per channel (in seconds)
Each array value coresponds with the audio channel.
example:
total_length: 480.1
cross_silence: 201.34
cross_talk: 11.2
talk_times:
- 87.45
- 145.32
ResultsPhrases:
title: Result of the phrase search.
description: Phrases found in the recording.
type: object
properties:
phrases_found:
type: array
items:
type: object
description: 'Single phrase searched'
properties:
text:
type: string
description: 'A phrase text (echo from Phrases model)'
findings:
description: 'All occurrences found in the recording'
type: array
items:
type: object
properties:
channel:
type: integer
description: 'Channel index (e.g. 0 or 1 for a stereo audio file)'
from:
type: number
format: float
description: 'Beginning of the phrase occurrence (in secs)'
to:
type: number
format: float
description: 'End of the phrase occurrence (in secs)'
confidence:
type: number
format: float
description: 'Phrase was found with this confidence'
language:
type: string
description: |
Language of the Phrase set (e.g. en-US).
See https://tools.ietf.org/html/rfc5646 or http://www.lingoes.net/en/translator/langcode.htm
example:
language: en-US
phrases_found:
-
text: hello
findings:
-
channel: 0
from: 5.33
to: 5.98
confidence: 47.74
-
channel: 1
from: 2.13
to: 3.58
confidence: 87.14
-
text: can i help ya
-
text: well not exactly
-
text: how are you
findings:
-
channel: 1
from: 4.13
to: 3.76
confidence: 77.14
CallbackResponse:
title: Succesful Callback Response
description: An empty response required
type: object
additionalProperties: false
CallbackRequest:
title: Asynchronous analytic job response
description: |
Asynchronous speech analytic results:
- simple statistics
- phrase search
- transcripts (in the future).
type: object
properties:
_links:
type: object
properties:
recording_audio:
description: The accessible location of the audio recording.
type: object
properties:
href:
type: string
format: url
required:
- href
required:
- recording_audio
outcome:
type: string
enum:
- completed
- failed
tasks_result:
type: object
properties:
statistics:
$ref: '#/definitions/ResultsStatistics'
phrase_spotting:
$ref: '#/definitions/ResultsPhrases'
required:
- _links
- outcome
example:
_embedded:
recording:
_links:
audio:
href: 'http://example.com/external_storage/42/recordings/4354235_34.wav'
outcome: completed
tasks_result:
statistics:
total_length: 480.1
cross_silence: 201.34
cross_talk: 11.2
talk_times:
- 87.45
- 145.32
phrase_spotting:
language: en-US
phrases_found:
-
text: hello
findings:
-
channel: 0
from: 5.33
to: 5.98
confidence: 47.74
-
channel: 1
from: 2.13
to: 3.58
confidence: 87.14
-
text: can i help ya
-
text: well not exactly
-
text: how are you
findings:
-
channel: 1
from: 4.13
to: 3.76
confidence: 77.14
JobAccepted:
title: The analytics job was accepted.
description: |
This is the information for the customer that the asynchronous job description was received.
Related resources (audio and phrases) are also referenced here.
type: object
properties:
status:
type: string
enum:
- queued
description: The status of the job. Currently, only 'queued' is supported.
required:
- status
example:
status: queued
# shared in definitions:
ProblemDetail:
title: Normalized response in the case of problems.
description: 'Please see https://tools.ietf.org/html/rfc7807'
type: object
properties:
type:
type: string
format: url
title:
type: string
status:
type: number
detail:
type: string
required:
- title
- detail
example:
type: https://developers.ytica.com/api/problems/bad-params
title: Bad parameters
detail: The required parameter missing.
status: 400
ProblemDetailAuth:
title: Example response in the case of auth issues
description: 'Please see https://tools.ietf.org/html/rfc7807'
type: object
properties:
type:
type: string
format: url
title:
type: string
status:
type: number
detail:
type: string
required:
- title
- detail
example:
type: https://developers.ytica.com/api/problems/auth-failed
title: Authorization failed
detail: Insufficient parmissions in the auth token.
status: 403
# }} m4 preprocessor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment