Services

Services provide responses to API endpoint requests. A service is the same as a “view” that you might see in many web frameworks.

The reason we’re using the convention “service” is because we’re focusing on creating API endpoints.

Defining a service

A service can be as simple as a function in your application:

from guillotina import configure
from guillotina.interfaces import IContainer

@configure.service(context=IContainer, name='@myservice', method='GET',
                   permission='guillotina.AccessContent')
async def my_service(context, request):
    return {
        'foo': 'bar'
    }

The most simple way to define a service is to use the decorator method shown here.

As long as your application imports the module where your service is defined, your service will be loaded for you.

In this example, the service will apply to a GET request against a container, /zodb/guillotina/@myservice.

Note

Scanning

If your service modules are not imported at run-time, you may need to provide an additional scan call to get your services noticed by guillotina.

In your application __init__.py file, you can simply provide a scan call like

from guillotina import configure
def includeme(root):
    configure.scan('my.package')

Class-based services

For more complex services, you might want to use class-based services.

With the class-based approach, the example above will look like this:

from guillotina import configure
from guillotina.interfaces import IContainer
from guillotina.api.service import Service

@configure.service(context=IContainer, name='@myservice', method='GET',
                   permission='guillotina.AccessContent')
class MyService(Service):
    async def __call__(self):
        return {
            'foo': 'bar'
        }

Special cases

I want that my service is accessible no matter the content

You can define in the service configuration with allow_access=True which tells the security checker to ignore checking for the default permission guillotina.AccessContent.

from guillotina import configure
from guillotina.interfaces import IResource
@configure.service(
    context=IResource, name='@download',
    method='GET', permission='guillotina.Public',
    allow_access=True)
async def my_service(context, request):
    pass