simpleapi Documentation

Transcription

1 simpleapi Documentation Release Florian Schlachter July 06, 2014

2

3 Contents 1 Contents User s Guide Developer s Reference Additional Pages Easy example handlers.py (in your django app) in django: urls.py in Flask: app.py Python Client (using simpleapi s client library) PHP Client (using simpleapi s PHP client) JavaScript Client (using jquery) Python Module Index 15 i

4 ii

5 simpleapi is an easy to use, consistent, transparent and portable way of providing an API. It supports several transport formats (e. g. json, jsonp, xml, yaml) and provides server (django, flask) and client libraries (PHP, Python) to interact seamlessly. You can also use nearly every Ajax framework (e. g. jquery, ExtJS, etc.) to access the API. To install, simply run: # pip install --upgrade simpleapi The source is available on GitHub. You can als follow simpleapi on to stay up-to-date. Warning: This documentation is uncomplete and will be finished over the next few weeks. Please be patient. Contents 1

6 2 Contents

7 CHAPTER 1 Contents 1.1 User s Guide Preparation Dependencies In order to use simpleapi, you must have Python and at least django or Flask installed. If you re using Python <= 2.5 you have to install simplejson by: pip install --upgrade simplejson Python >= 2.6 contains a built-in json module which already fits our needs. Installation PyPI You can either install a stable version of simpleapi from PyPI using easy_install or pip: easy_install -U simpleapi or pip install simpleapi GitHub If you re brave you can use the latest development version: git clone git://github.com/flosch/simpleapi.git Please consider yourself warned: The bleeding edge version might contain bugs, new features, backwardincompatibility issues and more problems you might not think of. 3

8 Manual Setup If you don t like one of the easy ways to install simpleapi, you can also download the latest version of simpleapi from GitHub as an tgz or zip file. To install simpleapi on your computer, unpack the compressed file and run: python setup.py install Depending on your system s configuration, you must be an administrator to install simpleapi Getting Started The Basics The Server Implementation A basic server implementation contains one Namespace and one Route. The Namespace holds all your API logic and implementation, the Route connects your Namespace to the world. When a client call comes in, Route will parse the request, checks whether all required arguments exist and will finally pass them to your method. For you, the user of simpleapi, Route is fairly unspectacular. The more interesting part is the Namespace. The Namespace is a bunch of published and non-published methods. Published methods are accessable from outside, non-published methods are your internally used methods (called helper functions). A Namespace can have several global and local configuration options for authentication, ip restrictions, type conversion, constraints, features (like caching, throttling, etc.) and input/output formatters. Even though the common way for placing your Namespace is to use handlers.py, you re free to put it wherever you like. As you already saw on the frontpage, an example implementation of handlers.py would look like this: from simpleapi import Namespace class Calculator(Namespace): def add(self, a, b): return a + b add.published = True This is a very easy, but still working calculator with only one function add(). With the local configuration option published set to True we export the method add() to the world. It requires two arguments, a and b. To finally make our exported functions available to the world with django, we hook up an URL to our Route. Route takes our Namespace as an argument. In this example, the URL api/calculator/ is used to access our Calculator-API: from simpleapi import Route from handlers import Calculator urlpatterns = patterns(, (r ^api/calculator/$, Route(Calculator)) ) Route takes care of all incoming requests and - in our example - makes sure that the two required arguments a and b of our add()-function exist. 4 Chapter 1. Contents

9 Client Libraries simpleapi comes with easy-to-use python and php client libraries which allows you fully, transparently access to your server implementation. With the client libraries, you call the desired remote function as they would be local. The only difference between a remote call using the library and a local call are the obligatory named arguments. On every remote call you must name your arguments when passing them to the function: from simpleapi import Client calculator = Client(ns= ) print "5 + 3 =", calculator.add(a=5, b=3) As you can see, the required arguments a and b are explicitly named and passed to the function add(). Internally, the client determines which function you want to call, builds an appropriate query and sends the request to the server. The server response is being received and parsed by the client and the return value is passed to you Server Namespaces Namespaces contain your business logic. They are normal Python classes and are being implemented very intuitively. Here s how an example looks like: import urllib import re from simpleapi import Namespace class Downloader(Namespace): def download(self, url): """Downloads a webpage and returns the full sourcecode.""" try: response = urllib.urlopen(url) print response.getcode() except IOError, e: self.error(unicode(e)) return response.read() download.published = True download.constraints = { url : re.compile(r ^http\://[a-za-z0-9\-\.]+\.[a-za-z]{2,3}(/\s*)?$ )} As you can see simpleapi works pretty much like common RPC-implementations. Every method within your Namespace flagged with the published-keyword set to True will be exposed by simpleapi to the remote clients. For more information on how Namespaces work see the following subpages. Contents Validation Session Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum User s Guide 5

10 Authentication IP Restrictions Error handling Route Features Client Python client library simpleapi ships with a Python client library which makes the communication between Python apps a snap. It s absolutely seamless, transparent and easy to use. This is how a remote call looks like on the client side: from simpleapi import Client client = Client(ns= ) print "Mom s birthday is on:", client.get_birthday("mom").ctime() ns takes the URL of your API. It can either be a http or a https (preferred) address for a secure connection. As you can see simpleapi can work with data objects (for instance datetime-objects). In special this depends on the used data protocol (for example JSON, XML, Pickle, etc.), but the common data types like strings, integers, floats, lists, dicts and datetimes are supported by all of them. For more limitations on transport types see Limitations and work-arounds. By default, the Python client library uses JSON as a transport type (for requests as well as responses), but you re free to change that by passing the transport_type parameter to the constructor containing your desired formatter name. For available built-in formatters (or writing your own ones), see the Messages documentation part. Multiple versions of Namespaces simpleapi supports multiple versions of Namespaces (e. g. for the case that your API evolves over time and existing method behaviour changes). By default, the client automatically uses the latest provided version. If you want to stay at one Namespace version and want to use it anytime, you can supply your desired version number by passing it to the version argument of client s constructor. Authentication If your Namespace requires an authentication key you can supply one using the access_key parameter passing to the client s constructor. There s nothing special about that. If the authentication fails, the client will raise a RemoteException (see more below for Exception handling). Long running calls For remote calls which take long time to proceed (for example a newsletter which is send to a bunch of recipients and your client application is still waiting for an OKAY) the constructor has a timeout parameter which takes the 6 Chapter 1. Contents

11 desired response timeout in seconds (default depends on your system s configuration). Set it as high as you want and as your system support it, e.g. timeout = 600 for 10 minutes. Exception handling To handle connection problems or remote exceptions the client raises two types of errors: ConnectionException and RemoteException. The client library throws a ConnectionException whenever there are problems with receiving the data from the given URL. These exceptions are covering all the network communication stuff, instead of RemoteException which basically raises when the client reaches the API but the specific call fails (in all situations like authentication failed, wrong parameters, user-generated errors). In both situations the exception message contains more information about the error (especially the error message in most cases). PHP client library Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. JavaScript client Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Same-domain requests (JSON) Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Cross-site requests (JSONP) Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Raw HTTP request simpleapi communicates using HTTP and therefore takes some parameters which will be discussed here. Sample call: /api/?_call=multiply&_access_key=foobar&a=5&b=11 _call method name (from the Namespace you re calling) 1.1. User s Guide 7

12 _access_key Key to access the Namespace (default: empty) _callback When using JSONP, defines the callback function (default: simpleapicallback). _mimetype Individual mimetype differing from the default one (note: simpleapi sets the correct mimetype depending on your desired output format). Hint: If you want to see the response in your browser (instead of download like some browsers want to), set the mimetype to text/html. _data Takes an object containing all function parameters (default: empty). See below for more. _version Defines which version of your Namespaces to use (default: latest). _input Format type (see Formatters) to use (e. g. JSON, JSONP, XML, etc.) for the request parameters (default: value, see below) _output Format type (see Formatters) to use (e. g. JSON, JSONP, XML, etc.) for the response (default: JSON) _wrapper Wrapper name of the wrapper to use to form the response (see Wrappers). All parameters except _call are optional. Method arguments If you call a method, you frequently have to pass arguments to the method. In simpleapi you can do this in two ways. Either you just append the parameter to your HTTP call (like a and b in the sample call above) or you use the _data http parameter to provide an object (a dictionary/associative array) with your parameters inside. Regardless which way you use, you have to encode your parameters depending on your _input http parameter. By default, there s no input-encoding set (hence you can pass your arguments plain). Note that you ve to set an input encoding since value (plain) is prohibited when using the _data parameter Messages simpleapi has several ways of converting, wrapping and formatting the transported messages (requests and responses). Due to protocol restrictions there are a few limitations and possible work-arounds which are worth to recommend. Wrappers Formatters Limitations and work-arounds JSON and datetimes By default, JSON does not support datetimes as a data type. simpleapi takes care of this automatically and converts any datetime, date and time objects to a special format which is supported by JavaScript s Date-object. If your Namespace method returns a datetime like: datetime.datetime(2010, 6, 2, 12, 0, 35, ) simpleapi will converts this into the following string representation: 8 Chapter 1. Contents

13 Wed Jun 2 12:00: In JavaScript you can simply create a Date-object by passing the converted string to the constructor like this new Date("Wed Jun 2 12:00: ") The Date-object will parse the string and convert it. Between both the simpleapi server and the Python client working with datetimes is absolutely seamless and transparent. As seen the server will convert the datetime into a string representation and the Python client (unfortunately not the PHP client yet) will detect this string representation and will convert it back into appropriate datetime, date and time objects. 1.2 Developer s Reference API Client Python class simpleapi.client.client(ns, access_key=none, version= default, transport_type= json, wrapper_type= default, timeout=none) simpleapi s client library. Parameters ns URL of your Route s endpoint access_key string key used for authentication version Namespace version to be used (default is highest) transport_type encoding/decoding type for request/response (default is json) wrapper_type wrapper used for formatting the response timeout connection timeout in secs (default is system parameter) set_ns(ns) changes the URL for the Route s endpoint set_version(version) uses a different version for further requests Server Route class simpleapi.server.route.route Namespace class simpleapi.server.namespace.namespace(request) 1.2. Developer s Reference 9

14 error(*errors) introspect(framework= default, provider= Ext.app, namespace=none) exception simpleapi.server.namespace.namespaceexception(msg=none) Features class simpleapi.server.feature.feature(ns_config) error(errmsg) get_config(request) get_config_scope(request) handle_request(request) handle_response(response) has_config() is_triggered(request) setup() exception simpleapi.server.feature.featureexception(msg=none) exception simpleapi.server.feature.featurecontentresponse(msg=none) Request class simpleapi.server.request.request(sapi_request, namespace, input_formatter, output_formatter, wrapper, callback, mimetype, restful, debug, route, ignore_unused_args) process_request(request_items) exception simpleapi.server.request.requestexception(msg=none) Response class simpleapi.server.response.response(sapi_request, namespace=none, output_formatter=none, wrapper=none, errors=none, result=none, mimetype=none, callback=none, function=none) add_error(errmsg) build(skip_features=false, managed=false) has_errors() class simpleapi.server.response.responsemerger(sapi_request, responses) build() class simpleapi.server.response.responseexception 10 Chapter 1. Contents

15 class simpleapi.server.response.unformattedresponse(content, mimetype= text/html ) Session class simpleapi.server.session.session clear() Utils class simpleapi.server.utils.glob_list A list which is Unix shell-style wildcards searchable Message Formatter class simpleapi.message.formatter.formatterssingleton This singleton takes care of all registered formatters. You can easily register your own formatter for use in both the Namespace and python client. register(name, formatter, override=false) Register the given formatter. If there s already an formatter with the given name, you can override by setting override to True. class simpleapi.message.formatter.formatter(sapi_request, callback) Baseclass for Formatter-implementations build(value) Takes care of the building process and returns the encoded data. kwargs(value, action= build ) Is called within simpleapi. This method invokes both the parse and build function when needed. parse(value) Takes care of the parsing proccess and returns the decoded data. class simpleapi.message.formatter.jsonformatter(sapi_request, callback) Formatter for the JSON-format. Used by default by the python client and by many Javascript-Frameworks. class simpleapi.message.formatter.jsonpformatter(sapi_request, callback) Formatter for JSONP-format. Used for cross-domain requests. If callback isn t provided, simpleapicallback is used. class simpleapi.message.formatter.valueformatter(sapi_request, callback) Basic formatter for simple, fast and tiny transports (it has a lot of limitations, though). class simpleapi.message.formatter.pickleformatter(sapi_request, callback) Formatter for use the cpickle python module which supports python object serialization. It has the fewest limitations (ie. it can also serialize datetime objects), but is a security risk and should only be used in a trusted environment. It s strongly recommended that you use authentication mechanismen to protect your namespace. The formatter is not activated by default and can be enabled by putting pickle into Namespace s input and output configuration Developer s Reference 11

16 Wrapper class simpleapi.message.wrapper.wrapperssingleton This singleton takes care of all registered wrappers. You can easily register your own wrapper for use in both the Namespace and python client. register(name, wrapper, override=false) Register the given wrapper class simpleapi.message.wrapper.wrapper(sapi_request) The baseclass wrapper you can use as a basis for your own wrapper class simpleapi.message.wrapper.defaultwrapper(sapi_request) class simpleapi.message.wrapper.extjsformwrapper(sapi_request) Request objects 1.3 Additional Pages Credits Thanks to... Stephan Jaekel and Martin Mahner for their inspiration and testing. 12 Chapter 1. Contents

17 CHAPTER 2 Easy example 2.1 handlers.py (in your django app) from simpleapi import Namespace class Calculator(Namespace): def add(self, a, b): return a + b add.published = True 2.2 in django: urls.py from simpleapi import Route from handlers import Calculator urlpatterns = patterns(, (r ^api/calculator/$, Route(Calculator)) ) 2.3 in Flask: app.py from simpleapi import Route from handlers import Calculator from flask import Flask app = Flask( name ) app.route( /api/ )(Route(Calculator, framework= flask )) if name == main : app.run() 13

18 2.4 Python Client (using simpleapi s client library) from simpleapi import Client calculator = Client(ns= ) print "5 + 3 =", calculator.add(a=5, b=3) 2.5 PHP Client (using simpleapi s PHP client) <?php $calculator = new Client(ns= ); print("5 + 3 ".$calculator->add(array( a =>5, b =>3)));?> 2.6 JavaScript Client (using jquery) jquery.get( "/api/calculator/", {_call: add, a: 5, b: 3}, function (result) { alert( = + result); } ) 14 Chapter 2. Easy example

19 Python Module Index s simpleapi.message.formatter, 11 simpleapi.message.wrapper, 12 simpleapi.server.feature, 10 simpleapi.server.namespace, 9 simpleapi.server.request, 10 simpleapi.server.response, 10 simpleapi.server.route, 9 simpleapi.server.session, 11 simpleapi.server.utils, 11 15