Metadata-Version: 2.1
Name: z3c.rest_publisher
Version: 0.7
Summary: This product has the base classes to implement a REST-Server using the concepts of Zope-traverser (IBrowserPublisher)
Home-page: http://svn.plone.org/svn/collective/
Author: Rodrigo Ristow
Author-email: rodrigo@maxttor.com
License: GPL
Description: 
        z3c.rest_publisher Package
        ==========================
        
        Overview
        --------
        
        This product registers Zope-traverses (IBrowserPublisher) to implement basic REST requests in a simpler way.
        This is done by registering traversable objects (IBrowserPublisher) to represent each method or level of the REST API.
        No documents or folders will be accessed directly. It is necessary to create classes for each information to be accessed by the API.
        
        For example, in the following request:
        
            curl http://localhost:8080/api/members/my_user
        
        where
         - api - It's a view (inherited from APIBase) registered for ROOT
         - members - It's a object inherited from APIBase included in "api"
         - myuser - It's a object inherited from APIBase included in "members"
        
        Install
        -------
        
        pip install z3c.rest_publisher
        
        Configuration
        -------------
        
        1 - API Root
        The starting point for the API is a traditional view registered in Zope ZCML. e.g.
        
        ```xml
        <view
        name="api"
        for="zope.location.interfaces.IRoot"
        type="zope.publisher.interfaces.browser.IBrowserRequest"
        provides="zope.publisher.interfaces.browser.IBrowserPublisher"
        factory=".rest_api.APIRoot"
        permission="zope.Public"
        allowed_attributes="publishTraverse browserDefault __call__">
        </view>
        ```
        
        Authentication
        --------------
        
        1 - Zope-Authentication
        You can use traditional Zope systems for authentication, for example by changing permissions for the view
        
            permission="zope.Public"
            or
            permission="zope.ManageContent"
        
        2 - Custom authentication
        
        If you wish, you can include customized authentication for the API. Just overwrite the "check_authentication" method in the class.
        For example, to implement a basic authentication:
        
            class APIRoot(APIBase):
                def check_authentication(self):
                    user, pwd = self.request._authUserPW()
                    return user == 'demo' and pwd == 'demo'
        
        To test:
        
            curl --user demo:demo  http://localhost:8080/api/
        
        REST functions
        --------------
        
        There are two ways to add a REST function to the Object.
        
        1 - REST function as a method
        Include a method in the format {HTTP-Method}_{Name} (lower-case), e.g.
        
            class APIRoot(APIBase):
                def get_list_admins(self):
                    return [{'id': '1', 'firstname': 'Alberto', 'lastname': 'Santos-Dumont'},
                            {'id': '2', 'firstname': 'Edson', 'lastname': 'Arantes do Nascimento'}]
                def put_list_admins(self):
                    return self.get_list_admins()
        
        To test:
        
            curl -X GET http://localhost:8080/api/list_admins
            curl -X PUT http://localhost:8080/api/list_admins
        
        2 - Concatenated REST objects
        It is possible to create a new REST object and concatenate it with the current object.
        This is the equivalent implementation from the previous method.
        
            class APIListAdmins(APIBase):
                def get(self):
                    return [{'id': 'user1', 'firstname': 'Alberto', 'lastname': 'Santos-Dumont'},
                            {'id': 'user2', 'firstname': 'Edson', 'lastname': 'Arantes do Nascimento'}]
                def put(self):
                    return self.get()
        
            class APIRoot(APIBase):
                content = {'list_admins': APIListAdmins}
        
        To test:
        
            curl -X GET http://localhost:8080/api/list_admins
            curl -X PUT http://localhost:8080/api/list_admins
        
        2.1 - REST function for objects (catch all)
        To implement a "generic" traverse to access specific database objects, use the wildcard "*".
        
            class APIUSer(APIBase):
                def get(self):
                    if self.name == 'user1'
                        return {'id': 'user1', 'firstname': 'Alberto', 'lastname': 'Santos-Dumont'}
                    elif self.name == 'user2':
                        return {'id': 'user2', 'firstname': 'Edson', 'lastname': 'Arantes do Nascimento'}
                    else:
                        self.request.response.setStatus(404)
                        return "User not found"
        
            class APIMembers(APIBase):
                content = {'*': APIUSer}
        
            class APIRoot(APIBase):
                content = {'members': APIListAdmins}
        
        To test:
        
            curl -X GET http://localhost:8080/api/members/user1
        
        API documentation
        -----------------
        
        The class RestDoc provide a simple built-in documentation of all REST-APi methods. 
        The default url is '[API_ROOT]/help' but you can change the property 'doc_endpoint' (APIBase) if you desire.
        
        
        Example
        -------
        
        Please see "z3c.rest_publisher/example" for an example.
        
        
        Changelog
        =========
        
        0.7 (05.05.20)
        --------------
        
        - Added the built-in documentation (default: /help) for the REST API
        
        
        0.4 (01.05.20)
        --------------
        
        - Initial release
        
        
Keywords: REST Zope IBrowserPublisher
Platform: UNKNOWN
Classifier: Programming Language :: Python
Description-Content-Type: text/x-rst
