.. TurboGears Web Services documentation master file, created by
   sphinx-quickstart on Thu Jan 28 17:05:51 2010.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to TurboGears Web Services's documentation!
===================================================

:Author: The TurboGears Development Team <turbogears-web-services@googlegroups.com>
:Copyright: Copyright 2008, 2009, 2010 The TurboGears Development Team
:Author: Kevin Dangoor <dangoor+tgwebservices@gmail.com>
:Copyright: Copyright 2006, 2007 Kevin Dangoor and Arbor Networks
:License: MIT
:Homepage: http://code.google.com/p/tgws/

.. contents:: Table of Contents

Introduction
------------

TurboGears gives you a plain HTTP with JSON return values API for your
application for free. This isn't always what you want, though. Sometimes,
you don't want to expose all of the data to the web that you need to
render your templates. Maybe you need to support a protocol that names the
function it's calling as part of what it POSTs such as SOAP or XML-RPC.

TGWebServices provides a super simple API for creating web services that
are available via SOAP, HTTP->XML, and HTTP->JSON. The SOAP API generates
WSDL automatically for your Python and even generates enough type
information for statically typed languages (Java and C#, for example) to
generate good client code on their end.

How easy is it?

::

    class Multiplier(WebServicesRoot):

        @wsexpose(int)
        @wsvalidate(int, int)
        def multiply(self, num1, num2):
            return num1 * num2

With this at the root, SOAP clients can find the WSDL file at
``/soap/api.wsdl`` and POST SOAP requests to ``/soap/``. HTTP requests to
``/multiply?num1=5&num2=20`` will return an XML document with the result of
100. Add ``?tg_format=json`` (or an HTTP ``Accept: text/javascript`` header)
and you'll get JSON back.

The great thing about this is that the code above looks like a '''normal
Python function''' and doesn't know a thing about web services.

Prerequisites
-------------

This document assumes a working knowledge of TurboGears.

Features
--------

* Easiest way to expose a web services API
* Supports SOAP, HTTP+XML, HTTP+JSON
* Outputs wrapped document/literal SOAP, which is the most widely
  compatible format
* Provides enough type information for statically typed languages to
  generate conveniently usable interfaces
* Can output instances of your own classes
* Can input instances of your own classes (via SOAP, XML or JSON)
* Works with TurboGears 1.0
* MIT license allows for unrestricted use

Getting Help
------------

Questions about TGWebServices should go to the TurboGears Web Services mailing list.

http://groups.google.com/group/turbogears-web-services

Content
=======

.. toctree::
   :maxdepth: 1

   usage
   documenting

   clientside

   tutorial/index

   api

   changelog

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`