Skip to end of metadata
Go to start of metadata

Asterisk Client Library Generator

Generator for client libraries for Asterisk's REST API which is provided by res_http_stasis.

Languages

  • Python
  • JavaScript
  • Perl
  • format such that additional language support is not difficult.

Library structure

  • Top-level library or object or structure
    • Asterisk.get_info()
    • Endpoints.get_endpoints()
    • Channels.get_channels()
    • Bridges.get_bridges()
    • Recordings.get_recordings()
    • Endpoint.get_endpoint(id)
    • Channel.get_channel(id)
    • Bridges.get_bridge(id)
    • Recordings.get_recording(id)
    • add_event_handler(event_name, function)
    • remove_event_handler(event_name, function)
  • Each object in the Swagger resource files
    • Methods listed therein
    • Relevant object attribute getters
    • add_event_handler(event_name, function)
    • remove_event_handler(event_name, function)

Library behavior

HTTP codes

  • 2XX - no error. If we got a JSON response, return it, else, return void.
  • 3XX - followed by HTTP libraries
  • 400 Bad Request - used when the requested action cannot be attempted because of bad params. Throw an IllegalInputException.
  • 404 Not Found - used when the object to be acted upon doesn't exist. Throw a NotFoundException.
  • 409 Conflict - used when the requested action cannot be attempted because of bad state. Throw an IllegalStateException.
  • 500 - Throw an AsteriskServerException.
  • 501 - Throw a NoSuchMethodException.
  • 5XX - Throw a AsteriskUnknownException.

    Python

  • Methods should return the object specified in the Swagger documentation or throw an appropriate exception.

    Perl

  • Methods should return the object specified in the Swagger documentation if the call succeeds. Undecided as of yet how error-handling will take place. We will avoid setting an error variable which may be over written by subsequent or parallel calls.

    JavaScript

  • Methods should pass the object specified in the Swagger documentation into a success handler (2xx). Fatal errors (400, 418, 5XX) will cause an error to be throw. Non-fatal errors will call an error handler (404, 409).

Project location and directory structure

This project is located on GitHub. Inside asterisk_rest_libraries

  • No labels

4 Comments

  1. Erin

    On the naming....

    I am seeing a lot of python-YOURNAMEHERE style naming and it does make sense. Just my thoughts.

    • python-asterisk
    • js-asterisk
    • perl-asterisk
  2. How does one go about writing a generator for another language?

    1. The project is more of an experiment in its current form, but if you'd like to play with adding additional languages, please do. At the very least, it may help us find ways to improve this concept or a reason to abandon it.

      To add support for a new language:

      1. Add new directories and files for the new language, i. e.:
        • $LANGUAGE
        • $LANGUAGE/lib
        • $LANGUAGE/templates
        • $LANGUAGE/config.json
        • lib/$LANGUAGE.py
      2. In $LANGUAGE/config.json, configure the common name of the language and its file extension. I see in the file addressed in #5 that this information is duplicated there. I am not sure if this is a mistake. It may be left-over.
      3. In $LANGUAGE/lib, design the importable/linkable module according to the conventions of the language.
      4. In $LANGUAGE/templates, modify the templates according to the syntax of the language.
      5. In lib/$LANGUAGE.py, write some formatting functions in python to create things like file, class, and method names; comments; parameter definitions and handling; and if desired, a function for wrapping lines of code.
  3. Good question Matt.

    We're still working through what the generators are going to end up looking like. A lot of the RESTful interface in Asterisk 12 is actually already auto-generated from a defined model using Mustache templates. In fact, a different set of templates also generates the documentation for the REST interface on the wiki (in the Asterisk 12 development section). We'll probably move the REST client libraries over to Mustache relatively soon (see ASTERISK-22149).

    Hopefully, what that means is that generating the skeleton of a client library for a new language becomes just a matter of creating new templates for that language. I'd expect that any auto-generated client libraries are only going to be a starting point - auto-generation only takes you so far - but that's the goal at any rate.