diff options
author | David M. Lee <dlee@digium.com> | 2013-04-22 14:58:53 +0000 |
---|---|---|
committer | David M. Lee <dlee@digium.com> | 2013-04-22 14:58:53 +0000 |
commit | 1c21b8575bfd70b98b1102fd3dd09fc0bc335e14 (patch) | |
tree | 9a6ef6074e545ad2768bc1994e1a233fc1443729 /rest-api/api-docs/sounds.json | |
parent | 1871017cc6bd2e2ce7c638eeb6813e982377a521 (diff) |
This patch adds a RESTful HTTP interface to Asterisk.
The API itself is documented using Swagger, a lightweight mechanism for
documenting RESTful API's using JSON. This allows us to use swagger-ui
to provide executable documentation for the API, generate client
bindings in different languages, and generate a lot of the boilerplate
code for implementing the RESTful bindings. The API docs live in the
rest-api/ directory.
The RESTful bindings are generated from the Swagger API docs using a set
of Mustache templates. The code generator is written in Python, and
uses Pystache. Pystache has no dependencies, and be installed easily
using pip. Code generation code lives in rest-api-templates/.
The generated code reduces a lot of boilerplate when it comes to
handling HTTP requests. It also helps us have greater consistency in the
REST API.
(closes issue ASTERISK-20891)
Review: https://reviewboard.asterisk.org/r/2376/
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386232 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'rest-api/api-docs/sounds.json')
-rw-r--r-- | rest-api/api-docs/sounds.json | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/rest-api/api-docs/sounds.json b/rest-api/api-docs/sounds.json new file mode 100644 index 000000000..23d02257d --- /dev/null +++ b/rest-api/api-docs/sounds.json @@ -0,0 +1,85 @@ +{ + "_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.", + "_author": "David M. Lee, II <dlee@digium.com>", + "_svn_revision": "$Revision$", + "apiVersion": "0.0.1", + "swaggerVersion": "1.1", + "basePath": "http://localhost:8088/stasis", + "resourcePath": "/api-docs/sounds.{format}", + "apis": [ + { + "path": "/sounds", + "description": "Sounds", + "operations": [ + { + "httpMethod": "GET", + "summary": "List all sounds.", + "nickname": "getSounds", + "responseClass": "List[Sound]", + "parameters": [ + { + "name": "lang", + "paramType": "query", + "dataType": "string", + "required": false + }, + { + "name": "format", + "paramType": "query", + "dataType": "string", + "required": false, + "__note": "core show translation can show translation paths between formats, along with relative costs. so this could be just installed format, or we could follow that for transcoded formats." + } + ] + } + ] + }, + { + "path": "/sounds/{soundId}", + "description": "Individual sound", + "operations": [ + { + "httpMethod": "GET", + "summary": "Get a sound's details.", + "nickname": "getStoredSound", + "responseClass": "Sound", + "parameters": [ + { + "name": "soundId", + "description": "Sound's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + } + ], + "models": { + "Sound": { + "id": "Sound", + "properties": { + "id": { + "required": true, + "description": "Sound's identifier.", + "type": "string" + }, + "text": { + "required": false, + "description": "Text description of the sound, usually the words spoken.", + "type": "string" + }, + "lang": { + "required": true, + "type": "string" + }, + "formats": { + "required": true, + "type": "List[string]" + } + } + } + } +} |