{"id":13725333,"url":"https://github.com/dropbox/stone","last_synced_at":"2025-05-07T20:32:09.578Z","repository":{"id":8769005,"uuid":"59315128","full_name":"dropbox/stone","owner":"dropbox","description":"The Official API Spec Language for Dropbox API V2","archived":false,"fork":false,"pushed_at":"2024-05-15T15:51:51.000Z","size":2518,"stargazers_count":397,"open_issues_count":14,"forks_count":76,"subscribers_count":32,"default_branch":"main","last_synced_at":"2024-05-16T15:52:07.824Z","etag":null,"topics":["api","dropbox","dropbox-api","dropbox-v2","generator","python","stone"],"latest_commit_sha":null,"homepage":"https://www.dropbox.com/developers","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dropbox.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-20T17:55:45.000Z","updated_at":"2024-05-31T12:52:41.165Z","dependencies_parsed_at":"2023-02-17T04:45:54.161Z","dependency_job_id":"5cc4e3c6-ff05-420f-9524-c6dc99b498c9","html_url":"https://github.com/dropbox/stone","commit_stats":{"total_commits":724,"total_committers":71,"mean_commits":10.19718309859155,"dds":0.4834254143646409,"last_synced_commit":"bdd49bc1017dcea2d193beb1925cded33a276d54"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fstone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fstone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fstone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fstone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dropbox","download_url":"https://codeload.github.com/dropbox/stone/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224645331,"owners_count":17346126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","dropbox","dropbox-api","dropbox-v2","generator","python","stone"],"created_at":"2024-08-03T01:02:19.750Z","updated_at":"2024-11-14T15:31:13.235Z","avatar_url":"https://github.com/dropbox.png","language":"Python","readme":".. image:: https://cfl.dropboxstatic.com/static/images/sdk/stone_banner.png\n    :target: https://github.com/dropbox/stone\n\n.. image:: https://img.shields.io/pypi/pyversions/stone.svg\n    :target: https://pypi.python.org/pypi/stone\n\n.. image:: https://img.shields.io/pypi/v/stone.svg\n    :target: https://pypi.python.org/pypi/stone\n\n.. image:: https://codecov.io/gh/dropbox/stone/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/dropbox/stone\n\nThe Official Api Spec Language for Dropbox.\n\n`Documentation`_ can be found on GitHub\n\nInstallation\n============\n\nInstall stone using ``pip``::\n\n    $ pip install --user stone\n\nThis will install a script ``stone`` to your PATH that can be run from the\ncommand line::\n\n    $ stone -h\n\nStone requires Python 3.\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\u003e=3.4\" \"six\u003e=1.3.0\" \"typing\u003e=3.5.2\"\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    $ PYTHONPATH=path/to/stone python -m stone.cli -h\n\nAfter installation, follow one of our `Examples`_ or read the `Documentation`_.\n\n\nOverview\n========\n\nDefine an API once in Stone. Use backends, i.e. code generators, to translate\nyour specification into objects and functions in the programming languages of\nyour choice.\n\n* Introduction\n    * Motivation_\n    * Installation_\n* `Language Reference \u003chttps://github.com/dropbox/stone/blob/main/docs/lang_ref.rst\u003e`_\n* `Builtin Backends \u003chttps://github.com/dropbox/stone/blob/main/docs/builtin_backends.rst\u003e`_\n* `Managing Specs \u003chttps://github.com/dropbox/stone/blob/main/docs/managing_specs.rst\u003e`_\n* `Evolving a Spec \u003chttps://github.com/dropbox/stone/blob/main/docs/evolve_spec.rst\u003e`_\n* `Backend Reference \u003chttps://github.com/dropbox/stone/blob/main/docs/backend_ref.rst\u003e`_\n* `JSON Serializer \u003chttps://github.com/dropbox/stone/blob/main/docs/json_serializer.rst\u003e`_\n* `Network Protocol \u003chttps://github.com/dropbox/stone/blob/main/docs/network_protocol.rst\u003e`_\n\n*Warning: The documentation is undergoing a rewrite.*\n\n.. image:: docs/overview.png\n\nStone is made up of several components:\n\nLanguage\n--------\n\nA language for writing API specifications, \"specs\" for short.\n\nCommand-Line Interface\n----------------------\n\nThe CLI (``stone``) generates code based on the provided specs, backend,\nand additional arguments.\n\nBackends\n--------\n\nThere are builtin backends that come with Stone: Javascript, Python, Obj-C,\nSwift, and Typescript.\n\nThere are other backends we've written that aren't part of the Stone package\nbecause they aren't sufficiently general, and can't realistically be re-used\nfor non-Dropbox APIs: Go and Java.\n\nStone includes a Python interface for defining new backends based on its\nintermediate representation of specs. This gives you the freedom to generate\nto any target.\n\nJSON Serialization\n------------------\n\nStone defines a JSON-compatible serialization scheme.\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 \u003chttps://github.com/google/protobuf\u003e`_.\n\nStone is in active use for the `Dropbox v2 API\n\u003chttp://www.dropbox.com/developers\u003e`_.\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 -\u003e 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\nExamples\n========\n\nWe provide `Examples`_ to help get you started with a lot of the basic functionality of Stone.\n\nGetting Help\n============\n\nIf you find a bug, please see `CONTRIBUTING.md`_ for information on how to report it.\n\nIf you need help that is not specific to Stone, please reach out to `Dropbox Support`_.\n\nLicense\n=======\n\nStone is distributed under the MIT license, please see `LICENSE`_ for more information.\n\n.. _logo: {logo_link}\n.. _repo: https://github.com/dropbox/stone\n.. _`Documentation`: https://github.com/dropbox/stone/tree/main/docs\n.. _`Examples`: https://github.com/dropbox/stone/tree/main/example/backend\n.. _LICENSE: https://github.com/dropbox/stone/blob/main/LICENSE\n.. _CONTRIBUTING.md: https://github.com/dropbox/stone/blob/main/CONTRIBUTING.md\n.. _`Dropbox Support`: https://www.dropbox.com/developers/contact\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdropbox%2Fstone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdropbox%2Fstone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdropbox%2Fstone/lists"}