Changeset 7
- Timestamp:
- 02/09/07 15:17:52 (2 years ago)
- Files:
-
- trunk/README.txt (modified) (6 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
trunk/README.txt
r1 r7 12 12 ------------ 13 13 14 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. 14 TurboGears gives you a plain HTTP with JSON return values API for your 15 application for free. This isn't always what you want, though. Sometimes, 16 you don't want to expose all of the data to the web that you need to 17 render your templates. Maybe you need to support a protocol that names the 18 function it's calling as part of what it POSTs such as SOAP or XML-RPC. 15 19 16 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. 20 TGWebServices provides a super simple API for creating web services that 21 are available via SOAP, HTTP->XML, and HTTP->JSON. The SOAP API generates 22 WSDL automatically for your Python and even generates enough type 23 information for statically typed languages (Java and C#, for example) to 24 generate good client code on their end. 17 25 18 26 How easy is it? … … 27 35 return num1 * num2 28 36 29 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. 37 With this at the root, SOAP clients can find the WSDL file at 38 /soap/api.wsdl and POST SOAP requests to /soap/. HTTP requests to 39 /multiply?num1=5&num2=20 will return an XML document with the result of 40 100. Add ?tg_format=json (or an HTTP Accept: text/javascript header) and 41 you'll get JSON back. 30 42 31 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. 43 The great thing about this is that the code above looks like a '''normal 44 Python function''' and doesn't know a thing about web services. 32 45 33 46 Prerequisites … … 41 54 * Easiest way to expose a web services API 42 55 * Supports SOAP, HTTP+XML, HTTP+JSON 43 * Outputs wrapped document/literal SOAP, which is the most widely compatible format 44 * Provides enough type information for statically typed languages to generate conveniently usable interfaces 56 * Outputs wrapped document/literal SOAP, which is the most widely 57 compatible format 58 * Provides enough type information for statically typed languages to 59 generate conveniently usable interfaces 45 60 * Can output instances of your own classes 46 61 * Works with TurboGears 1.0 … … 73 88 74 89 1. Those are all of the imports that you'll likely need 75 2. The top level controller must subclass WebServicesRoot. This is important, because this provides the /soap URL that is required for SOAP access. 90 2. The top level controller must subclass WebServicesRoot. This is 91 important, because this provides the /soap URL that is required for 92 SOAP access. 76 93 3. wsexpose is called with the type that is returned from the method. 77 4. wsvalidate is called with the types of the parameters. You can specify the types positionally (*skipping self*) or as keyword arguments to wsvalidate. 78 5. Unlike when you work with TurboGears proper, you do not need to return a dictionary. Just return the value directly. 94 4. wsvalidate is called with the types of the parameters. You can specify 95 the types positionally (*skipping self*) or as keyword arguments to 96 wsvalidate. 97 5. Unlike when you work with TurboGears proper, you do not need to return 98 a dictionary. Just return the value directly. 79 99 80 100 Lists 81 101 ----- 82 102 83 When you wish to return an array of items, you can specify this by creating a list that contains one item: the type of the objects in the list:: 103 When you wish to return an array of items, you can specify this by 104 creating a list that contains one item: the type of the objects in the 105 list:: 84 106 85 107 @wsexpose([str]) … … 87 109 return ["A", "B", "C"] 88 110 89 Since many web services are consumed by statically typed languages like Java, lists that are returned as SOAP arrays can only contain *one* type of object. 111 Since many web services are consumed by statically typed languages like 112 Java, lists that are returned as SOAP arrays can only contain *one* type 113 of object. 90 114 91 115 Custom Objects 92 116 -------------- 93 117 94 You can return instances of classes that you create. Whenever you see the term "complex type", you can think "class". "Complex type" comes from XML Schema terminology that is used in declaring the properties of the returned type. 118 You can return instances of classes that you create. Whenever you see the 119 term "complex type", you can think "class". "Complex type" comes from XML 120 Schema terminology that is used in declaring the properties of the 121 returned type. 95 122 96 Returning complex types is as easy as returning primitive types. However, you do need to take an extra step in declaring complex types that you wish to return. Here is an example:: 123 Returning complex types is as easy as returning primitive types. However, 124 you do need to take an extra step in declaring complex types that you wish 125 to return. Here is an example:: 97 126 98 127 class FancyValue(object): … … 117 146 return fv 118 147 119 In this example, we've created a class called FancyValue that we want to return from a web service method. TGWebServices will only return properties of instances that:: 148 In this example, we've created a class called FancyValue that we want to 149 return from a web service method. TGWebServices will only return 150 properties of instances that: 120 151 121 * are declared at the class level (in the example above, name is defined as a string and age is defined as an int) 152 * are declared at the class level (in the example above, name is defined 153 as a string and age is defined as an int) 122 154 * do not start with _ 123 155 * are not methods 124 156 125 With these rules, it's easy to store whatever housekeeping data you need on your objects without exposing that data to the web service. 157 With these rules, it's easy to store whatever housekeeping data you need 158 on your objects without exposing that data to the web service. 126 159 127 Once you've defined your class, you can specify it as a return value in wsexpose just as you would a builtin Python type. 160 Once you've defined your class, you can specify it as a return value in 161 wsexpose just as you would a builtin Python type. 128 162 129 See the next section for information about *typedproperty* which appears in the example above. 163 See the next section for information about *typedproperty* which appears 164 in the example above. 130 165 131 At this time, TGWebServices doesn't support instances and lists as input parameters. 166 At this time, TGWebServices doesn't support instances and lists as input 167 parameters. 132 168 133 169 Extra Types You Can Return 134 170 -------------------------- 135 171 136 The tgwebservices.runtime defines two additional types that you can return: unsigned and typedproperty. Python doesn't have an unsigned int type, but you can use the tgwebservices.runtime.unsigned class to tell the consumer of your service that you are returning an unsigned integer value. 172 The tgwebservices.runtime defines two additional types that you can 173 return: unsigned and typedproperty. Python doesn't have an unsigned int 174 type, but you can use the tgwebservices.runtime.unsigned class to tell the 175 consumer of your service that you are returning an unsigned integer value. 137 176 138 typedproperty wraps the standard Python property function allowing you to specify what return type will be coming from your property's getter method. In the example in the previous section, the "computed" property will be a string. 177 typedproperty wraps the standard Python property function allowing you to 178 specify what return type will be coming from your property's getter 179 method. In the example in the previous section, the "computed" property 180 will be a string. 139 181 140 182 Getting Help
