json-api-schema

<!DOCTYPE html> <html> <head> <meta charset='UTF-8'> <title>JSON API Schema Documentation</title> <link rel='stylesheet' href='assets/codo.css' type='text/css'> <script src='assets/codo.js'></script> <script src='assets/search_data.js'></script> </head> <body> <div id='base' data-path=''></div> <div id='header'> <div id='menu'> <a href='README.md.html' title='JSON API Schema'>JSON API Schema</a> » <a href='class_index.html' title='Index'>Index</a> » <span class='title'>README.md</span> <nav> <ul> <li class='noframes'> (<a class='noframes' href='#'>no frames</a>) </li> </ul> </nav> <div id='search'> <a id='class_list_link' href='class_list.html'>Classes</a> <a id='file_list_link' href='file_list.html'>Files</a> <a id='method_list_link' href='method_list.html'>Methods</a> <a id='extra_list_link' href='extra_list.html'>Extras</a> </div> </div> <iframe id='search_frame'></iframe> <div id='fuzzySearch'> <input type='text'> <ol></ol> </div> <div id='help'> <p> Quickly fuzzy find classes, mixins, methods, file: </p> <ul> <li> <span>Ctrl-T</span> Open fuzzy finder dialog </li> </ul> <p> In frame mode you can toggle the list naviation frame on the left side: </p> <ul> <li> <span>Ctrl-L</span> Toggle list view </li> </ul> <p> You can focus a list in frame mode or toggle a tab in frameless mode: </p> <ul> <li> <span>Ctrl-C</span> Class list </li> <li> <span>Ctrl-I</span> Mixin list </li> <li> <span>Ctrl-F</span> File list </li> <li> <span>Ctrl-M</span> Method list </li> <li> <span>Ctrl-E</span> Extras list </li> </ul> <p> You can focus and blur the search input: </p> <ul> <li> <span>Ctrl-S</span> Focus search input </li> <li> <span>Esc</span> Blur search input </li> </ul> <p> In frameless mode you can close the list tab: </p> <ul> <li> <span>Esc</span> Close list tab </li> </ul> </div> </div> <div id='content'> <nav class='toc'> <p class='title'> <a class='hide_toc' href='#'> <strong>Table of Contents</strong> </a> <small> (<a class='float_toc' href='#'>left</a>) </small> </p> </nav> <div id='filecontents'> <h1>JSON Api Schema</h1> <h2>A Json based Web API Description Language and Object Model</h2><p><strong>JSON Api Schema</strong> is a JSON dialect ( just a json file ) that can describe any Web Based API that uses JSON to exchange data.</p><p>A <strong>JSON Api Schema</strong> can be used to share an unabiguous object model between servers and clients along with validation logic, classes and so on.</p><p>In other words <strong>JSON Api Schema</strong> is a set of two related specification:</p><ul> <li><strong>JSON Api Schema-DL</strong>: A JSON API Description Language</li> <li><strong>JSON Api Schema-OM</strong>: A related API Object Model (similar of what DOM is to HTML)</li> </ul> <h3>Design goals</h3> <h4>Be generic enough to describe complex systems</h4><p><strong>JSON Api Schema</strong> is designed to express a generic API minimizing constraints on implementations. <strong>JSON Api Schema</strong> Description Language can support applicaition specific behaviours through extensions. JSON Api Schema is designed to be able to express a super-set of RESTful APIs and JSON APIs, as a mean to communicate interactions and data structures exposed by an API. Application specific stuffs are expressed through protocol options.</p><h4>Be available in multiple languages</h4><p><strong>JSON Api Schema</strong> Object Model adopt conventions that make it easy to be implemented in most languages. For example we use getters and setters over properties and accessors, iterators instead of closures, ecc...</p><h4>Be suitable to readapt existing data models</h4><p>Being easy to implement in both clients and servers <strong>JSON Api Schema</strong> is perfect to renew an old data source.</p><h4>Be a real-world solution</h4><p>To be different from other well known solution it primarly targets modern web development (A Javascript friendly solution, easy to map validation errors to form fields, support for websockets, EventSources ecc..., and more over not be a two billion SLOC framework).</p><h4>Allow to share validation logic between servers and clients</h4><p><strong>JSON Api Schema</strong> heavily relies on JSON Schema to export validation logic to clients.</p><h4>Be suitable to build RMI on top of it</h4><p>Implementing Types <strong>JSON Api Schema</strong> makes it easy (but not forces) to hide network requests behind OOP objects and classes.</p><h4>Be documentable</h4><p><strong>JSON Api Schema</strong> support documentation attributes everywhere. A traversable model make it easy to generate a beautiful readable documentation. </p><h3>A typical use case</h3><p>An application consists of a data api, a website and a mobile app: - They are 3 separate systems that may be written in different languages. - They shares the same domain model.</p><p>Data Api exports its interface through <strong>JSON Api Schema</strong>. Website and Mobile App consumes that through dynamically or statically generated stubs, or either by directly calling actions via ajax requests.</p><h2>Specification</h2> <h3>Api Model (For Both DL and OM):</h3> <h4>Api</h4><p>The entry point of the model. An Api is a set of interactions, types and resources. An api exposes also protocol specific global informations to configure interactions.</p><h4>Resource</h4><p>A Resource is a type that has interactions. A Resource can have nested resources. Nested resources are somewhat logically bound to their container, eg. by ID or by URI.</p><h4>Schema</h4><p>A JSON Schema instance. Anything that can be validated should have or be a schema.</p><h4>Type</h4><p>Just a named <code>Schema</code>.</p><h4>Interactions</h4><p>An interaction is a communication available with the api. It can represent both a client-initiated communication or a server initiated communication. Protocol based informations about an interaction are stored in a <code>protocols</code> map.</p><h5>Action</h5><p>An action is a client initiated interaction. It has two validatable sub-entities along with protocol specification: <code>params</code> and <code>returns</code></p><h5>Event</h5><p>An event is a server initiated interaction. It has a validatable sub-entity along with protocol specification: <code>params</code>.</p> </div> </div> <div id='footer'> Generated on Fri Sep 20 2013 14:12:12 GMT+0200 (CEST) by <a href='https://github.com/netzpirat/codo' title='CoffeeScript API documentation generator'>Codo</a> v1.7.2 (Node.js v0.10.15). ✲ Press Ctrl-h to see the keyboard shortcuts ✲ <a href='http://twitter.com/#!/netzpirat'>@netzpirat</a> ✲ <a href='https://mksoft.ch'>mksoft.ch</a> </div> </body> </html>