endpoints


Nameendpoints JSON
Version 7.3.1 PyPI version JSON
download
home_pageNone
SummaryGet an api up and running quickly
upload_time2025-02-06 23:36:37
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseThe MIT License (MIT) Copyright (c) 2013+ Jay Marcyes Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords asgi asgi-server wsgi wsgi-server api api-server server framework web-framework rest rest-api
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Endpoints

_Endpoints_ is a lightweight REST api framework written in python that supports both WSGI and ASGI. _Endpoints_ has been used in multiple production systems that handle millions of requests daily.


## Getting Started

### Installation

First, install endpoints with the following command.

    $ pip install endpoints

If you want the latest and greatest you can also install from source:

    $ pip install -U "git+https://github.com/jaymon/endpoints#egg=endpoints"


### Create a Controller Module

Create a controller file with the following command:

    $ touch controllers.py

Add the following code to the `controllers.py` file:

```python
from endpoints import Controller

class Default(Controller):
  """The special class `Default` handles / requests"""
  async def GET(self):
    return "Default handler"

  async def POST(self, **kwargs):
    return 'hello {}'.format(kwargs['name'])

class Foo(Controller):
  """This class handles `/foo` requests"""
  async def GET(self):
    return "Foo handler"
```


### Start a WSGI Server

Now that you have your `controllers.py`, let's use the built-in WSGI server to serve them, we'll set our `controllers.py` file as the [controller prefix](docs/PREFIXES.md) so Endpoints will know where to find the [Controller classes](docs/CONTROLLERS.md) we just defined:

    $ endpoints --prefix=controllers --host=localhost:8000


### Start an ASGI Server

Install [Daphne](https://github.com/django/daphne):

    $ pip install -U daphne

And start it:

    $ ENDPOINTS_PREFIX=controllers daphne -b localhost -p 8000 -v 3 endpoints.interface.asgi:Application.factory


### Test it out

Using curl:

    $ curl http://localhost:8000
    "Default handler"
    $ curl http://localhost:8000/foo
    "Foo handler"
    $ curl http://localhost:8000/ -d "name=Awesome you"
    "hello Awesome you"

That's it!

In the ***first request*** (`/`), the `controllers` module was accessed, then the `Default` class, and then the `GET` method.

In the ***second request*** (`/foo`), the `controllers` module was accessed, then the `Foo` class as specified in the path of the url, and then the `GET` method.

Finally, in the ***last request***, the `controllers` module was accessed, then the `Default` class, and finally the `POST` method with the passed in argument.


## How does it work?

*Endpoints* translates requests to python modules without any configuration.

It uses the following convention.

    METHOD /module/class/args?kwargs

_Endpoints_ will use the prefix module you set as a reference point to find the correct submodule using the path specified by the request.

Requests are translated from the left bit to the right bit of the path.
So for the path `/foo/bar/che/baz`, endpoints would first check for the `foo` module, then the `foo.bar` module, then the `foo.bar.che` module, etc. until it fails to find a valid module.

Once the module is found, endpoints will then attempt to find the class with the remaining path bits. If no matching class is found then a class named `Default` will be used if it exists.

This makes it easy to bundle your controllers into a `controllers` package/module.


## Learn more about Endpoints

The [docs](https://github.com/jaymon/endpoints/tree/master/docs) contain more information about how _Endpoints_ works and what can be done with it.


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "endpoints",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "asgi, asgi-server, wsgi, wsgi-server, api, api-server, server, framework, web-framework, REST, rest-api",
    "author": null,
    "author_email": "Jay Marcyes <jay@marcyes.com>",
    "download_url": "https://files.pythonhosted.org/packages/65/36/df0d7cd2bc330e886b7f6491b35a7fb7386c595b03aa93719d7a007ca62c/endpoints-7.3.1.tar.gz",
    "platform": null,
    "description": "# Endpoints\n\n_Endpoints_ is a lightweight REST api framework written in python that supports both WSGI and ASGI. _Endpoints_ has been used in multiple production systems that handle millions of requests daily.\n\n\n## Getting Started\n\n### Installation\n\nFirst, install endpoints with the following command.\n\n    $ pip install endpoints\n\nIf you want the latest and greatest you can also install from source:\n\n    $ pip install -U \"git+https://github.com/jaymon/endpoints#egg=endpoints\"\n\n\n### Create a Controller Module\n\nCreate a controller file with the following command:\n\n    $ touch controllers.py\n\nAdd the following code to the `controllers.py` file:\n\n```python\nfrom endpoints import Controller\n\nclass Default(Controller):\n  \"\"\"The special class `Default` handles / requests\"\"\"\n  async def GET(self):\n    return \"Default handler\"\n\n  async def POST(self, **kwargs):\n    return 'hello {}'.format(kwargs['name'])\n\nclass Foo(Controller):\n  \"\"\"This class handles `/foo` requests\"\"\"\n  async def GET(self):\n    return \"Foo handler\"\n```\n\n\n### Start a WSGI Server\n\nNow that you have your `controllers.py`, let's use the built-in WSGI server to serve them, we'll set our `controllers.py` file as the [controller prefix](docs/PREFIXES.md) so Endpoints will know where to find the [Controller classes](docs/CONTROLLERS.md) we just defined:\n\n    $ endpoints --prefix=controllers --host=localhost:8000\n\n\n### Start an ASGI Server\n\nInstall [Daphne](https://github.com/django/daphne):\n\n    $ pip install -U daphne\n\nAnd start it:\n\n    $ ENDPOINTS_PREFIX=controllers daphne -b localhost -p 8000 -v 3 endpoints.interface.asgi:Application.factory\n\n\n### Test it out\n\nUsing curl:\n\n    $ curl http://localhost:8000\n    \"Default handler\"\n    $ curl http://localhost:8000/foo\n    \"Foo handler\"\n    $ curl http://localhost:8000/ -d \"name=Awesome you\"\n    \"hello Awesome you\"\n\nThat's it!\n\nIn the ***first request*** (`/`), the `controllers` module was accessed, then the `Default` class, and then the `GET` method.\n\nIn the ***second request*** (`/foo`), the `controllers` module was accessed, then the `Foo` class as specified in the path of the url, and then the `GET` method.\n\nFinally, in the ***last request***, the `controllers` module was accessed, then the `Default` class, and finally the `POST` method with the passed in argument.\n\n\n## How does it work?\n\n*Endpoints* translates requests to python modules without any configuration.\n\nIt uses the following convention.\n\n    METHOD /module/class/args?kwargs\n\n_Endpoints_ will use the prefix module you set as a reference point to find the correct submodule using the path specified by the request.\n\nRequests are translated from the left bit to the right bit of the path.\nSo for the path `/foo/bar/che/baz`, endpoints would first check for the `foo` module, then the `foo.bar` module, then the `foo.bar.che` module, etc. until it fails to find a valid module.\n\nOnce the module is found, endpoints will then attempt to find the class with the remaining path bits. If no matching class is found then a class named `Default` will be used if it exists.\n\nThis makes it easy to bundle your controllers into a `controllers` package/module.\n\n\n## Learn more about Endpoints\n\nThe [docs](https://github.com/jaymon/endpoints/tree/master/docs) contain more information about how _Endpoints_ works and what can be done with it.\n\n",
    "bugtrack_url": null,
    "license": "The MIT License (MIT)  Copyright (c) 2013+ Jay Marcyes  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
    "summary": "Get an api up and running quickly",
    "version": "7.3.1",
    "project_urls": {
        "Homepage": "https://github.com/Jaymon/endpoints",
        "Repository": "https://github.com/Jaymon/endpoints"
    },
    "split_keywords": [
        "asgi",
        " asgi-server",
        " wsgi",
        " wsgi-server",
        " api",
        " api-server",
        " server",
        " framework",
        " web-framework",
        " rest",
        " rest-api"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f81e0bded541f8415a321b9ba0b9bff3169a7c620c0adcd71aa6cc44d38e673c",
                "md5": "81998b915063bdc7a83fcd2602bffd24",
                "sha256": "1a055ac03e71a301e6c7be83bb675e73f9d3d15b895b45e360c90ecb42887d92"
            },
            "downloads": -1,
            "filename": "endpoints-7.3.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "81998b915063bdc7a83fcd2602bffd24",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 76940,
            "upload_time": "2025-02-06T23:36:36",
            "upload_time_iso_8601": "2025-02-06T23:36:36.026929Z",
            "url": "https://files.pythonhosted.org/packages/f8/1e/0bded541f8415a321b9ba0b9bff3169a7c620c0adcd71aa6cc44d38e673c/endpoints-7.3.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6536df0d7cd2bc330e886b7f6491b35a7fb7386c595b03aa93719d7a007ca62c",
                "md5": "c6fe613efd8968fbf5779cd4a87dcd48",
                "sha256": "6db0cf8173ea12f690be3809abaa09669c03d52f503dfdf38131f48c03472c75"
            },
            "downloads": -1,
            "filename": "endpoints-7.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "c6fe613efd8968fbf5779cd4a87dcd48",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 69753,
            "upload_time": "2025-02-06T23:36:37",
            "upload_time_iso_8601": "2025-02-06T23:36:37.624176Z",
            "url": "https://files.pythonhosted.org/packages/65/36/df0d7cd2bc330e886b7f6491b35a7fb7386c595b03aa93719d7a007ca62c/endpoints-7.3.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-06 23:36:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Jaymon",
    "github_project": "endpoints",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "endpoints"
}
        
Elapsed time: 1.37445s