Version 3.3 Documentation

REST outgoing connections

Don't Miss Out

Be sure to read the modern REST API tutorial in Python once you've finished this chapter.


REST outgoing connections allow one to invoke external REST-based endpoints.

  • URL paths can include patterns
  • Query string parameters are built from user-provided dictionaries
  • Payload can be automatically serialized to JSON or XML
  • Services can produce any and all headers the endpoint expects

For instance, let's assume that there is a POST REST endpoint at https://example.com which expects:

  • A URL path in the format of /customer/{cust_id}/phone_no/{phone_no}
  • Query string ?priority=normal
  • JSON payload {"billing":"395.7", "currency":"EUR"}
  • Custom HTTP headers, X-App-Name: Zato and X-Environment: Production

An outgoing connection and a service using it would read as follows:

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class SetBillingInfo(Service):
   """ Updates a customer's billing information.
   """
   def handle(self):

         # Python dict representing the payload we want to send across
         payload = {'billing':'395.7', 'currency':'EUR'}

         # Python dict with all the query parameters, including path and query string
         params = {'cust_id':'39175', 'phone_no':'271637517', 'priority':'normal'}

         # Headers the endpoint expects
         headers = {'X-App-Name': 'Zato', 'X-Environment':'Production'}

         # Obtains a connection object
         conn = self.outgoing.plain_http['SetBillingInfo'].conn

         # Invoke the resource providing all the information on input
         response = conn.post(self.cid, payload, params, headers=headers)

Notes:

  • As a programmer you never need to leave Python land, (de-)serialization is automatic and one can work with Python dataclasses or dictionaries only

  • The response object offers access to the whole of the body, headers and other metadata that the endpoint returns

  • Accessing JSON endpoints can be further simplified using by the dedicated JSON adapter

Continue your API learning journey