12 Commits (12)

Author	SHA1	Message	Date
Matthew Jordan	e970ea2dc4	api.wiki.mustache: Update wiki template to support body parameters ... This patch updates the api.wiki.mustache template and the swagger_model python script to understand if an operation has a body parameter. If an operation does have a body parameter, it will now be displayed in the corresponding wiki entry. git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/12@407389 65c4cc65-6c06-0410-ace0-fbb531ad65f3	11 years ago
David M. Lee	094c5e2cca	ari:Add application/json parameter support ... The patch allows ARI to parse request parameters from an incoming JSON request body, instead of requiring the request to come in as query parameters (which is just weird for POST and DELETE) or form parameters (which is okay, but a bit asymmetric given that all of our responses are JSON). For any operation that does _not_ have a parameter defined of type body (i.e. "paramType": "body" in the API declaration), if a request provides a request body with a Content type of "application/json", the provided JSON document is parsed and searched for parameters. The expected fields in the provided JSON document should match the query parameters defined for the operation. If the parameter has 'allowMultiple' set, then the field in the JSON document may optionally be an array of values. (closes issue ASTERISK-22685) Review: https://reviewboard.asterisk.org/r/2994/ git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/12@403175 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	2f92695c22	ari: User better nicknames for ARI operations ... While working on building client libraries from the Swagger API, I noticed a problem with the nicknames. channel.deleteChannel() channel.answerChannel() channel.muteChannel() Etc. We put the object name in the nickname (since we were generating C code), but it makes OO generators redundant. This patch makes the nicknames more OO friendly. This resulted in a lot of name changing within the res_ari_*.so modules, but not much else. There were a couple of other fixed I made in the process. * When reversible operations (POST /hold, POST /unhold) were made more RESTful (POST /hold, DELETE /unhold), the path for the second operation was left in the API declaration. This worked, but really the two operations should have been on the same API. * The POST /unmute operation had still not been REST-ified. Review: https://reviewboard.asterisk.org/r/2940/ git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/12@402528 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	5f31d0b182	The Swagger 1.2 specification for type extension ended up being ... slightly different than my proposal. Instead of putting an 'extends' field on the subtype, the base type has a 'subTypes' field, which is a list of the subTypes. Given that its a messaging model and not an object model, kinda makes sense. This patch changes the events.json api-doc, and the python translators to take the new format into account. Other changes that are in Swagger 1.2 were not adopted, since the spec is still in flux, and could change before it's finalized. A summary of changes to the Swagger-1.2 spec can be found at https://github.com/wordnik/swagger-core/wiki/1.2-transition. (closes issue ASTERISK-22440) Review: https://reviewboard.asterisk.org/r/2909/ git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/12@401701 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	5474e48966	optional_api: Fix linking problems between modules that export global symbols ... With the new work in Asterisk 12, there are some uses of the optional_api that are prone to failure. The details are rather involved, and captured on [the wiki][1]. This patch addresses the issue by removing almost all of the magic from the optional API implementation. Instead of relying on weak symbol resolution, a new optional_api.c module was added to Asterisk core. For modules providing an optional API, the pointer to the implementation function is registered with the core. For modules that use an optional API, a pointer to a stub function, along with a optional_ref function pointer are registered with the core. The optional_ref function pointers is set to the implementation function when it's provided, or the stub function when it's now. Since the implementation no longer relies on magic, it is now supported on all platforms. In the spirit of choice, an OPTIONAL_API flag was added, so we can disable the optional_api if needed (maybe it's buggy on some bizarre platform I haven't tested on) The AST_OPTIONAL_API*() macros themselves remained unchanged, so existing code could remain unchanged. But to help with debugging the optional_api, the patch limits the #include of optional API's to just the modules using the API. This also reduces resource waste maintaining optional_ref pointers that aren't used. Other changes made as a part of this patch: * The stubs for http_websocket that wrap system calls set errno to ENOSYS. * res_http_websocket now properly increments module use count. * In loader.c, the while() wrappers around dlclose() were removed. The while(!dlclose()) is actually an anti-pattern, which can lead to infinite loops if the module you're attempting to unload exports a symbol that was directly linked to. * The special handling of nonoptreq on systems without weak symbol support was removed, since we no longer rely on weak symbols for optional_api. [1]: https://wiki.asterisk.org/wiki/x/wACUAQ (closes issue ASTERISK-22296) Reported by: Matt Jordan Review: https://reviewboard.asterisk.org/r/2797/ git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/12@397989 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	a75fd32212	ARI - channel recording support ... This patch is the first step in adding recording support to the Asterisk REST Interface. Recordings are stored in /var/spool/recording. Since recordings may be destructive (overwriting existing files), the API rejects attempts to escape the recording directory (avoiding issues if someone attempts to record to ../../lib/sounds/greeting, for example). (closes issue ASTERISK-21594) (closes issue ASTERISK-21581) Review: https://reviewboard.asterisk.org/r/2612/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393550 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	c9a3d4562d	Update events to use Swagger 1.3 subtyping, and related aftermath ... This patch started with the simple idea of changing the /events data model to be more sane. The original model would send out events like: { "stasis_start": { "args": [], "channel": { ... } } } The event discriminator was the field name instead of being a value in the object, due to limitations in how Swagger 1.1 could model objects. While technically sufficient in communicating event information, it was really difficult to deal with in terms of client side JSON handling. This patch takes advantage of a proposed extension[1] to Swagger which allows type variance through the use of a discriminator field. This had a domino effect that made this a surprisingly large patch. [1]: https://groups.google.com/d/msg/wordnik-api/EC3rGajE0os/ey_5dBI_jWcJ In changing the models, I also had to change the swagger_model.py processor so it can handle the type discriminator and subtyping. I took that a big step forward, and using that information to generate an ari_model module, which can validate a JSON object against the Swagger model. The REST and WebSocket generators were changed to take advantage of the validators. If compiled with AST_DEVMODE enabled, JSON objects that don't match their corresponding models will not be sent out. For REST API calls, a 500 Internal Server response is sent. For WebSockets, the invalid JSON message is replaced with an error message. Since this took over about half of the job of the existing JSON generators, and the .to_json virtual function on messages took over the other half, I reluctantly removed the generators. The validators turned up all sorts of errors and inconsistencies in our data models, and the code. These were cleaned up, with checks in the code generator avoid some of the consistency problems in the future. * The model for a channel snapshot was trimmed down to match the information sent via AMI. Many of the field being sent were not useful in the general case. * The model for a bridge snapshot was updated to be more consistent with the other ARI models. Another impact of introducing subtyping was that the swagger-codegen documentation generator was insufficient (at least until it catches up with Swagger 1.2). I wanted it to be easier to generate docs for the API anyways, so I ported the wiki pages to use the Asterisk Swagger generator. In the process, I was able to clean up many of the model links, which would occasionally give inconsistent results on the wiki. I also added error responses to the wiki docs, making the wiki documentation more complete. Finally, since Stasis-HTTP will now be named Asterisk REST Interface (ARI), any new functions and files I created carry the ari_ prefix. I changed a few stasis_http references to ari where it was non-intrusive and made sense. (closes issue ASTERISK-21885) Review: https://reviewboard.asterisk.org/r/2639/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393529 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	dcf03554a0	Shuffle RESTful URL's around. ... This patch moves the RESTful URL's around to more appropriate locations for release. The /stasis URL's are moved to /ari, since Asterisk REST Interface was a more appropriate name than Stasis-HTTP. (Most of the code still has stasis_http references, but they will be cleaned up after there are no more outstanding branches that would have merge conflicts with such a change). A larger change was moving the ARI events WebSocket off of the shared /ws URL to its permanent home on /ari/events. The Swagger code generator was extended to handle "upgrade: websocket" and "websocketProtocol:" attributes on an operation. The WebSocket module was modified to better handle WebSocket servers that have a single registered protocol handler. If a client connections does not specify the Sec-WebSocket-Protocol header, and the server has a single protocol handler registered, the WebSocket server will go ahead and accept the client for that subprotocol. (closes issue ASTERISK-21857) Review: https://reviewboard.asterisk.org/r/2621/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393528 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
Kinsey Moore	7ce05bfb9b	Add channel events for res_stasis apps ... This change adds a framework in res_stasis for handling events from channel topics. JSON event generation and validation code is created from event documentation in rest-api/api-docs/events.json to assist in JSON event generation, ensure consistency, and ensure that accurate documentation is available for ALL events that are received by res_stasis applications. The userevent application has been refactored along with the code that handles userevent channel blob events to pass the headers as key/value pairs in the JSON blob. As a side-effect, app_userevent now handles duplicate keys by overwriting the previous value. Review: https://reviewboard.asterisk.org/r/2428/ (closes issue ASTERISK-21180) Patch-By: Kinsey Moore <kmoore@digium.com> git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@388275 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
Kinsey Moore	5eb184aa95	Fix spelling error in python doc ... git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386774 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	22aa2a6e9b	Oops. Mustache doesn't like dictionaries ... git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386461 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	1c21b8575b	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	12 years ago