{"id":16400165,"url":"https://github.com/jayrbolton/brontosaurus","last_synced_at":"2025-08-24T17:27:24.524Z","repository":{"id":145316760,"uuid":"234665715","full_name":"jayrbolton/brontosaurus","owner":"jayrbolton","description":"Streamlined Python JSON APIs with Sanic + JSON Schema + JSON RPC","archived":false,"fork":false,"pushed_at":"2020-03-16T17:45:15.000Z","size":168,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-04T23:43:02.056Z","etag":null,"topics":["json-rpc","json-rpc2","json-schemas","python","rpc","sanic"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jayrbolton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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":"2020-01-18T01:36:46.000Z","updated_at":"2020-04-01T16:49:51.000Z","dependencies_parsed_at":"2023-04-25T17:46:59.637Z","dependency_job_id":null,"html_url":"https://github.com/jayrbolton/brontosaurus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayrbolton%2Fbrontosaurus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayrbolton%2Fbrontosaurus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayrbolton%2Fbrontosaurus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayrbolton%2Fbrontosaurus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jayrbolton","download_url":"https://codeload.github.com/jayrbolton/brontosaurus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240306801,"owners_count":19780688,"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":["json-rpc","json-rpc2","json-schemas","python","rpc","sanic"],"created_at":"2024-10-11T05:26:54.317Z","updated_at":"2025-02-23T11:26:25.435Z","avatar_url":"https://github.com/jayrbolton.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cimg width='150' src='docs/logo.png' alt='logo'\u003e\u003c/img\u003e\n\n# brontosaurus - streamlined JSON APIs\n\nWrite small and fast API servers using:\n* Sanic - for a fast async http server\n* JSON Schema - for request and response validation and documentation\n* JSON RPC 2.0 - for a simple surrounding format\n* Python - for all your easy to read glue code\n\nSome benefits:\n* Automatic request validation\n* Autogenerated API documentation in markdown\n* Removes various RPC setup boilerplate\n* Handles bulk requests asynchronously with no extra code\n* Sets default values in requests and responses automatically\n* Automatically validates responses during development/test mode\n* Handles binary file uploads and responses\n\nIt is opinionated but customizable. The APIs are not resource-based, but instead use a method-call style from [JSON RPC 2.0](https://www.jsonrpc.org/specification) specification (for better or worse).\n\n**View a [quick code example](test/examples/pet_shop.py) along with its [auto-generated documentation](test/examples/docs/pet_shop_api.md)**.\n\n## API and Usage\n\n### `API(title, description)`\n\nCreate a new instance of the API object, which can be used to register methods and run the server.\n\n```py\nfrom brontosaurus import API\n\napi = API(\"Example API\", \"This is an example API server.\")\n```\n\nOptional keyword arguments:\n\n* `doc_path: str` - path (relative to the directory where the server runs) of the generated documentation. Ignored if not in development mode.\n\n### ` @api.method(name, summary)`\n\nRegister a method name and a short description. Used as a decorator around a function that handles the method.\n\nThe function receives the method parameters and the request headers as dictionaries.\n\n```py\n@api.method('no_op', 'Does nothing')\ndef no_op(params, headers):\n    pass\n```\n\n### ` @api.params(json_schema: dict)`\n\nSet the JSON Schema for the parameters for a method. Used as a decorator around\na method handler function. Documentation for your parameters can go inside the\n`title` and `description` properties in your schema.\n\n```py\n# JSON schema for some message\nmessage = {\n    'type': 'object',\n    'required': ['message'],\n    'properties': {\n        'message': {\n            'description': 'Any message that you want',\n            'type': 'string',\n        }\n    }\n}\n\n@api.method('log', 'Logs something in the backend')\n@api.params(message)\ndef no_op(params, headers):\n    logger.info(params)\n```\n\nSee the [JSON Schema](https://json-schema.org/understanding-json-schema/) guide for detailed information on how to write these schemas.\n\nIf you run the server (see below), you can now make the following request:\n\n```sh\n$ curl -d '{\"method\": \"log\", \"params\": {\"message\": \"hello world\"}}'\n```\n\n### ` @api.result(json_schema: dict)`\n\nSet the JSON Schema for the result for a method, useful for documentation and\ntests. Used as a decorator around a method handler function.\n\n```py\n# JSON schema for the params and the result\necho_message = {\n    'type': 'object',\n    'required': ['message'],\n    'properties': {\n        'message': {\n            'type': 'string'\n        }\n    }\n}\n\n@api.method('echo', 'Repeat a message back to you')\n@api.params(echo_message)\n@api.result(echo_message)\ndef echo(params, headers):\n    return {'message': params['message']}\n```\n\nNow you can make the following request:\n\n```sh\n$ curl -d '{\"method\": \"echo\", \"params\": {\"message\": \"hello world\"}}'\n\u003e {\"jsonrpc\": \"2.0\", \"id\": null, \"result\": {\"message\": \"hello world\"}}\n```\n\n### ` @api.deprecated(msg: str)`\n\nDecorator for marking a method as deprecated. Pass in a string message that describes the reason for the deprecation and other methods the user can use instead. The method will show up as deprecated with the deprecation message in the auto-generated docs.\n\n```py\n@api.method('hello_world')\n@api.deprecated('From now we do not need to say hello anymore.')\ndef hello_world(params, headers):\n    return 'hello world!'\n```\n\n### ` @api.subpath(path, title, description, **options)`\n\nYou can create multiple nested RPC APIs within a single server by using the `subpath` method. Each sub-path is a standalone, discrete JSON RPC API.\n\nSee a minimal example in [tests/examples/paths.py](tests/examples/paths.py).\n\n\n```py\nsubpath1 = api.subpath(\n    path='/subpath1\",\n    title=\"My Sub-API\",\n    description=\"This is an extended description\"\n)\n\n@subpath1.method('hello')\ndef subpath1_hello(params, header):\n    return 'hello from subpath1'\n```\n\nAdditional optional keyword arguments:\n\n* `doc_path: str` - path (relative to the directory where the server runs) of the generated documentation. Ignored if not in development mode.\n\n### `api.register(type_name: str, json_schema: dict)`\n\nRegister a JSON schema to be displayed in the API documentation. It does not\naffect the API, and only returns a plain dict of the schema.\n\nRegistered schemas must have an `\"$id\"` field, which will be used as its type name in the documentation. Typically these types are prepended with the hash symbol: `\"#name\"`.\n\n```py\nlogin_schema = api.register('login', {\n    '$id': '#login',\n    'title': 'Login data',\n    'type': 'object',\n    'properties': {\n        'password': {\n            'type': 'string',\n            'minLength': 7,\n        },\n        'email': {\n            'type': 'string',\n            'format': 'idn-email'\n        }\n    }\n})\n```\n\nNow, when you generate the documentation by running the server, the \"login\" schema will appear in the documentation. Anywhere that the schema is used in a method, a link will be generated to the documentation for this type.\n\n### `api.run(**kwargs)`\n\nRun the server.\n\nIn development mode, the documentation file will be generated. Also, the method\nresults will be validated against their JSON Schemas (but not in production).\n\nValid keyword arguments:\n\n* `host: str` - hostname to use (defaults to `'0.0.0.0'`)\n* `port: int` - port to use for the server (defaults to `8080`)\n* `development: bool` - whether we are in development mode (defaults to `True`)\n* `cors: bool` - whether to fully enable cross origin requests (defaults to `False`)\n* `workers: int` - how many async server workers to run (defaults to 2)\n\n### logger\n\nbrontosaurus comes with a logger that you can import:\n\n```py\nfrom brontosaurus import logger\n\nlogger.info('Hello world')\n```\n\nLog messages sent to this logger will show up both in stdout and in your app.log rotating log file.\n\n#### Development mode\n\nDevelopment mode has the following effects:\n\n* Markdown documentation is generated for your API(s) whenever the server is started\n* Response JSON structures are validated against their schemas\n* Logging level is set to DEBUG\n\n## Development\n\n### Run the tests\n\nInstall `poetry` with `pip install poetry`. Install dependencies with `poetry\ninstall`.\n\nRun the tests\n\n```sh\nmake test\n```\n\n### Contribution\n\nOpen an issue or PR\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayrbolton%2Fbrontosaurus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjayrbolton%2Fbrontosaurus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayrbolton%2Fbrontosaurus/lists"}