view release on metacpan or  search on metacpan

ds9-interface.html  view on Meta::CPAN

<p>Building interfaces for multiple languages, requires a machine
readable, language agnostic API specification. DS9 itself uses
generated lexer and parser Tcl code to interpret commands sent to it.
The parser and lexer specifications are in a proprietary DSL and
include Tcl code specific to DS9's internals, so are not easily
converted into a more generic grammar specification.</p>

<p>Of late encoding of HTTP REST API's has become commonplace via the
OpenAPI Specification (OAS) and RAML initiatives. These encode API
endpoints (<em>paths</em>), parameters and results as <code>YAML</code> or <code>JSON</code> data
structures (<code>RAML</code> only uses <code>YAML</code>).  Parameters and results may have
complex structures with types specified by<code>JSON</code> schema. 
As most languages in current use have some form of <code>JSON
Schema</code> validation, this provides a simple path to client-side parameter validation.
Tools exist to validate an API description, and to create test servers
and clients to evaluate it.</p>

<p>There are a few disadvantages of these specifications.</p>

<ol>

ds9-interface.md  view on Meta::CPAN

Building interfaces for multiple languages, requires a machine
readable, language agnostic API specification. DS9 itself uses
generated lexer and parser Tcl code to interpret commands sent to it.
The parser and lexer specifications are in a proprietary DSL and
include Tcl code specific to DS9's internals, so are not easily
converted into a more generic grammar specification.

Of late encoding of HTTP REST API's has become commonplace via the
OpenAPI Specification (OAS) and RAML initiatives. These encode API
endpoints (*paths*), parameters and results as `YAML` or `JSON` data
structures (`RAML` only uses `YAML`).  Parameters and results may have
complex structures with types specified by`JSON` schema. 
As most languages in current use have some form of `JSON
Schema` validation, this provides a simple path to client-side parameter validation.
Tools exist to validate an API description, and to create test servers
and clients to evaluate it.

There are a few disadvantages of these specifications.

1. Code generators for client support assume HTTP transport.  DS9 has three methods for transport.