{ "info": { "author": "Ken Elkabany", "author_email": "kelkabany@dropbox.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta" ], "description": "*****\nStone\n*****\n\n*Warning: The documentation is undergoing a rewrite.*\n\n.. image:: https://travis-ci.org/dropbox/stone.svg?branch=master\n :target: https://travis-ci.org/dropbox/stone\n\nDefine an API once in Stone. Use code generators to translate your\nspecification into objects and functions in the programming languages of your\nchoice.\n\nStone is made up of several components:\n\n 1. An interface-description language (IDL) for specifying APIs.\n 2. A command-line tool (``stone``) that takes an API specification and\n generator module, and generates output.\n 3. A Python-interface for defining new generators.\n 4. A JSON-compatible serialization format.\n\nStone is in active use for the `Dropbox v2 API\n`_. Right now, the only available generator\nis for Python, but we're working on releasing the other ones we have\ninternally: Swift, C#, Java, Go, JavaScript, and HTML documentation.\n\n * Introduction\n * Motivation_\n * Installation_\n * `Language Reference `_\n * `Builtin Generators `_\n * `Managing Specs `_\n * `Evolving a Spec `_\n * `Writing a Generator `_\n * `JSON Serializer `_\n * `Network Protocol `_\n\n.. _motivation:\n\nMotivation\n==========\n\nStone was birthed at Dropbox at a time when it was becoming clear that API\ndevelopment needed to be scaled beyond a single team. The company was\nundergoing a large expansion in the number of product groups, and it wasn't\nscalable for the API team, which traditionally dealt with core file operations,\nto learn the intricacies of each product and build corresponding APIs.\n\nStone's chief goal is to decentralize API development and ownership at Dropbox.\nTo be successful, it needed to do several things:\n\n**Decouple APIs from SDKS**: Dropbox has first-party clients for our mobile\napps, desktop client, and website. Each of these is implemented in a different\nlanguage. Moreover, we wanted to continue providing SDKs to third-parties, over\nhalf of whom use our SDKs. It's untenable to ask product groups that build APIs\nto also implement these endpoints in a half-dozen different language-specific\nSDKs. Without decoupling, as was the case in our v1 API, the SDKs will\ninevitably fall behind. Our solution is to have our SDKs automatically\ngenerated.\n\n**Improve Visibility into our APIs**: These days, APIs aren't just in the\ndomain of engineering. Product managers, product specialists, partnerships,\nsales, and services groups all need to have clear and accurate specifications\nof our APIs. After all, APIs define Dropbox's data models and functionality.\nBefore Stone, API design documents obseleted by changes during implementation\nwere the source of truth.\n\n**Consistency and Predictability**: Consistency ranging from documentation\ntense to API patterns are important for making an API predictable and therefore\neasier to use. We needed an easy way to make and enforce patterns.\n\n**JSON**: To make consumption easier for third parties, we wanted our data\ntypes to map to JSON. For cases where serialization efficiency\n(space and time) are important, you can try using msgpack (alpha support\navailable in the Python generator). It's possible also to define your own\nserialization scheme, but at that point, you may consider using something like\n`Protobuf `_.\n\nAssumptions\n-----------\n\nStone makes no assumptions about the protocol layer being used to make API\nrequests and return responses; its first use case is the Dropbox v2 API which\noperates over HTTP. Stone does not come with nor enforce any particular RPC\nframework.\n\nStone makes some assumptions about the data types supported in target\nprogramming languages. It's assumed that there is a capacity for representing\ndictionaries (unordered string keys -> value), lists, numeric types, and\nstrings.\n\nStone assumes that a route (or API endpoint) can have its argument and\nresult types defined without relation to each other. In other words, the\ntype of response does not change based on the input to the endpoint. An\nexception to this rule is afforded for error responses.\n\n.. _installation:\n\nInstallation\n============\n\nDownload or clone Stone, and run the following in its root directory::\n\n $ sudo python setup.py install\n\nThis will install a script ``stone`` to your PATH that can be run from the\ncommand line::\n\n $ stone -h\n\nAlternative\n-----------\n\nIf you choose not to install ``stone`` using the method above, you will need\nto ensure that you have the Python packages ``ply`` and ``six``, which can be\ninstalled through ``pip``::\n\n $ pip install ply>=3.4 six>=1.3.0\n\nIf the ``stone`` package is in your PYTHONPATH, you can replace ``stone``\nwith ``python -m stone.cli`` as follows::\n\n $ python -m stone.cli -h\n\nIf you have the ``stone`` package on your machine, but did not install it or\nadd its location to your PYTHONPATH, you can use the following::\n\n $ PYTOHNPATH=path/to/stone python -m stone.cli -h\n\n", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/dropbox/stone", "keywords": "", "license": "Copyright (c) 2014-2016 Dropbox Inc., http://www.dropbox.com/\r\n\r\n Permission is hereby granted, free of charge, to any person obtaining\r\n a copy of this software and associated documentation files (the\r\n \"Software\"), to deal in the Software without restriction, including\r\n without limitation the rights to use, copy, modify, merge, publish,\r\n distribute, sublicense, and/or sell copies of the Software, and to\r\n permit persons to whom the Software is furnished to do so, subject to\r\n the following conditions:\r\n\r\n The above copyright notice and this permission notice shall be\r\n included in all copies or substantial portions of the Software.\r\n\r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\r\n EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r\n MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r\n NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\r\n LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\r\n OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\r\n WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.", "maintainer": "", "maintainer_email": "", "name": "stone", "package_url": "https://pypi.org/project/stone/", "platform": "", "project_url": "https://pypi.org/project/stone/", "project_urls": { "Homepage": "https://github.com/dropbox/stone" }, "release_url": "https://pypi.org/project/stone/0.1/", "requires_dist": null, "requires_python": null, "summary": "", "version": "0.1" }, "last_serial": 2149644, "releases": { "0.1": [ { "comment_text": "", "digests": { "md5": "3f68bae7c18df4716de9623239b93e5d", "sha256": "a2a6f76db989a420277acf9fadc49a68b8a245d90541b453ef1d9d39f7163d9c" }, "downloads": -1, "filename": "stone-0.1-py2-none-any.whl", "has_sig": false, "md5_digest": "3f68bae7c18df4716de9623239b93e5d", "packagetype": "bdist_wheel", "python_version": "py2", "requires_python": null, "size": 89669, "upload_time": "2016-06-03T18:46:33", "url": "https://files.pythonhosted.org/packages/3a/ab/0d48cfc51202893eab7df2d75ee094ae6faf53d29ae28007d7b5bc137d34/stone-0.1-py2-none-any.whl" }, { "comment_text": "", "digests": { "md5": "d1086cc8d3b6334a3d5184afacf598db", "sha256": "6c4cc6a987c96127fbc99f9b57de35768c39d31c506b591de6399127b75c3b19" }, "downloads": -1, "filename": "stone-0.1-py3-none-any.whl", "has_sig": false, "md5_digest": "d1086cc8d3b6334a3d5184afacf598db", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 89664, "upload_time": "2016-06-03T18:46:41", "url": "https://files.pythonhosted.org/packages/36/42/030738d4eb9f4dfe83996a8a769aa5c1bdb71976080e9fd86357f178f60f/stone-0.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c6629ccd6872f504c783eef831566a22", "sha256": "a5dc2f7ed8596a269347b0db8d355ec73665d7dbf5065a692f0a4a29e3a2086d" }, "downloads": -1, "filename": "stone-0.1.tar.gz", "has_sig": false, "md5_digest": "c6629ccd6872f504c783eef831566a22", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 110657, "upload_time": "2016-06-03T18:46:48", "url": "https://files.pythonhosted.org/packages/d7/ab/724d1278485cd09e3cd87fda4b464b8c1f545bdbf883c0c9c8930045dfb0/stone-0.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "3f68bae7c18df4716de9623239b93e5d", "sha256": "a2a6f76db989a420277acf9fadc49a68b8a245d90541b453ef1d9d39f7163d9c" }, "downloads": -1, "filename": "stone-0.1-py2-none-any.whl", "has_sig": false, "md5_digest": "3f68bae7c18df4716de9623239b93e5d", "packagetype": "bdist_wheel", "python_version": "py2", "requires_python": null, "size": 89669, "upload_time": "2016-06-03T18:46:33", "url": "https://files.pythonhosted.org/packages/3a/ab/0d48cfc51202893eab7df2d75ee094ae6faf53d29ae28007d7b5bc137d34/stone-0.1-py2-none-any.whl" }, { "comment_text": "", "digests": { "md5": "d1086cc8d3b6334a3d5184afacf598db", "sha256": "6c4cc6a987c96127fbc99f9b57de35768c39d31c506b591de6399127b75c3b19" }, "downloads": -1, "filename": "stone-0.1-py3-none-any.whl", "has_sig": false, "md5_digest": "d1086cc8d3b6334a3d5184afacf598db", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 89664, "upload_time": "2016-06-03T18:46:41", "url": "https://files.pythonhosted.org/packages/36/42/030738d4eb9f4dfe83996a8a769aa5c1bdb71976080e9fd86357f178f60f/stone-0.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c6629ccd6872f504c783eef831566a22", "sha256": "a5dc2f7ed8596a269347b0db8d355ec73665d7dbf5065a692f0a4a29e3a2086d" }, "downloads": -1, "filename": "stone-0.1.tar.gz", "has_sig": false, "md5_digest": "c6629ccd6872f504c783eef831566a22", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 110657, "upload_time": "2016-06-03T18:46:48", "url": "https://files.pythonhosted.org/packages/d7/ab/724d1278485cd09e3cd87fda4b464b8c1f545bdbf883c0c9c8930045dfb0/stone-0.1.tar.gz" } ] }