Generating specifications for API services
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
In Zato 3.0, and already available if installed from source, a specification for such services will look like below:
- 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
- this is exactly what the next Zato version will do, it will generate specs in several formats for easy consumption by API clients.