Package: endpoints
EndpointsQuickest API builder in the West!Endpointsis a lightweight REST api framework written in python that supports both WSGI and ASGI.Endpointshas been used in multiple production systems that handle millions of requests daily.5 Minute Getting StartedInstallationFirst, install endpoints with the following command.$ pip install endpointsIf you want the latest and greatest you can also install from source:$ pip install -U "git+https://github.com/jaymon/endpoints#egg=endpoints"Set Up Your Controller FileCreate a controller file with the following command:$ touch controllers.pyAdd the following code to your new Controller file. These classes are examples of possibleendpoints.fromendpointsimportControllerclassDefault(Controller):asyncdefGET(self):return"boom"asyncdefPOST(self,**kwargs):return'hello{}'.format(kwargs['name'])classFoo(Controller):asyncdefGET(self):return"bang"Start a WSGI ServerNow that you have yourcontrollers.py, let's use the built-in WSGI server to serve them, we'll set ourcontrollers.pyfile as thecontroller prefixso Endpoints will know where to find theController classeswe just defined:$ endpoints --prefix=controllers --host=localhost:8000Start an ASGI ServerInstallDaphneand start it:$ ENDPOINTS_PREFIX=controllers daphne -b localhost -p 8000 -v 3 endpoints.interface.asgi.ApplicationFactoryTest it outUsing curl:$ curl http://localhost:8000
"boom"
$ curl http://localhost:8000/foo
"bang"
$ curl http://localhost:8000/ -d "name=Awesome you"
"hello Awesome you"That's it. Easy peasy!Can you figure out what path endpoints was following in each request?We see in thefirst requestthat the Controller module was accessed, then the Default class, and then the GET method.In thesecond request, the Controller module was accessed, then the Foo class as specified, and then the GET method.Finally, in thelast request, the Controller module was accessed, then the Default class, and finally the POST method with the passed in argument as JSON.How does it work?Endpointstranslates requests to python modules without any configuration.It uses the following convention.METHOD /module/class/args?kwargsEndpointswill use the base 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 check for thefoomodule, then thefoo.barmodule, then thefoo.bar.chemodule, 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 class is found the class namedDefaultwill be used.This makes it easy to bundle your controllers into something like a "Controllers" module.Below are some examples of HTTP requests and how they would be interpreted using endpoints.Note:prefix refers to the name of the base module that you set.HTTP RequestPath FollowedGET /prefix.Default.GET()GET /fooprefix.foo.Default.GET()POST /foo/barprefix.foo.Bar.POST()GET /foo/bar/cheprefix.foo.Bar.GET(che)GET /foo/bar/che?baz=fooprefix.foo.Bar.GET(che, baz=foo)POST /foo/bar/che with body: baz=fooprefix.foo.Bar.POST(che, baz=foo)As shown above, we see thatendpoints essentially travels the path from the base module down to the appropriate submodule according to the request given.One more exampleLet's say your site had the following setup:site/controllers/__init__.pyand the filecontrollers/__init__.pycontained:fromendpointsimportControllerclassDefault(Controller):asyncdefGET(self):return"called /"classFoo(Controller):asyncdefGET(self):return"called /foo"then your call requests would be translated like this:HTTP RequestPath FollowedGET /controllers.Default.GET()GET /foocontrollers.Foo.GET()If you have gotten to this point, congratulations. You understand the basics of endpoints. If you don't understand endpoints then please go back and read from the top again before reading any further.Learn more about EndpointsNow you should dive into some of the other features discussed in thedocs folder.