Generating specifications for API services

2017-03-08, by Dariusz Suchojad

This is a preview of an upcoming feature in Zato 3.0 that will let one generate and distribute specifications for [API services]/en/docs/3.3/intro/esb-soa.html).

Introduction

Let's consider the following two modules with three services related to customers and customer cases. The implementation is left out so as to focus on I/O only.

# api1.py

from zato.server.service import Service

namespace = 'my.api.customer'

class GetCustomer(Service):
    """ Returns basic information about a customer.
    """
    name = 'get-customer'

    class SimpleIO:
        input_required = ('cust_id',)
        input_optional = ('cust_type', 'segment',)
        output_required = ('name', 'is_active', 'region')
        output_optional = ('last_seen',)

    def handle(self):
        pass # Skip implementation

class UpdateCustomer(Service):
    """ Updates basic information about a customer.
    """
    name = 'update-customer'

    class SimpleIO:
        input_required = ('name', 'is_active', 'region')
        output_required = ('result',)

    def handle(self):
        pass # Skip implementation

# api2.py

from zato.server.service import Service

namespace = 'my.api.customer-cases'

class GetCustomerCase(Service):
    """ Returns basic information about an individual case opened by a customer.
    """
    name = 'get-customer-cases'

    class SimpleIO:
        input_required = ('case_id',)
        output_required = ('cust_id', 'is_open', 'status', 'last_contact_date',)
        output_optional = ('supervisor_id', 'region_id')

    def handle(self):
        pass # Skip implementation

Screenshots

In Zato 3.0, and already available if installed from source, a specification for such services will look like below:

Key points

• Services can be grouped into namespaces
• For each service its documentation, as extracted from docstrings, is provided
• Each service can optionally export information what other services it invokes, i.e. depends on
• Input/Output for each service is based on SimpleIO
• All parameters are automatically converted to correct types, e.g. is_active is a boolean, cust_id an integer
• Brand-specific information and CSS can be applied to customize the output - here 'My API spec' is only a generic name that can be replaced with anything else
• The API specification is output using a service and REST channels thus it can be secured as required just like any other channel in Zato

Future plans

While for now the output is the documentation, the underlying backend is already capable to automatically generate data for other API specification formats such as Swagger/OpenAPI, RAML or WSDL - this is exactly what the next Zato version will do, it will generate specs in several formats for easy consumption by API clients.