← Back to branch summary

~wallyworld/lazr.restful/namedpost-url-change-1056666

« back to all changes in this revision

Viewing changes to src/lazr/restful/docs/webservice-declarations.txt

  • Committer: Leonard Richardson
  • Date: 2011-03-09 17:05:42 UTC
  • mfrom: (176.4.16 must-specify-version)
  • Revision ID: leonard.richardson@canonical.com-20110309170542-ptak8uq9ffrov12y
[r=abentley] Make it possible to require an explicit version number for every exported field.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/lazr/restful/docs/webservice-declarations.txt
847
847
Generating the webservice
848
848
=========================
849
849
 
 
850
Setup
 
851
-----
 
852
 
 
853
Before we can continue, we must define a web service configuration
 
854
object. Each web service needs to have one of these registered
 
855
utilities providing basic information about the web service. This one
 
856
is just a dummy.
 
857
 
 
858
    >>> from lazr.restful.testing.helpers import TestWebServiceConfiguration
 
859
    >>> from zope.component import provideUtility
 
860
    >>> from lazr.restful.interfaces import IWebServiceConfiguration
 
861
    >>> class MyWebServiceConfiguration(TestWebServiceConfiguration):
 
862
    ...     active_versions = ["beta", "1.0", "2.0", "3.0"]
 
863
    ...     last_version_with_mutator_named_operations = "1.0"
 
864
    ...     first_version_with_total_size_link = "2.0"
 
865
    ...     code_revision = "1.0b"
 
866
    ...     default_batch_size = 50
 
867
    >>> provideUtility(MyWebServiceConfiguration(), IWebServiceConfiguration)
 
868
 
 
869
We must also set up the ability to create versioned requests. This web
 
870
service has four versions: 'beta', '1.0', '2.0', and '3.0'.  We'll
 
871
need a marker interface for every version, registered as a utility
 
872
under the name of the version.
 
873
 
 
874
Each version interface subclasses the previous version's
 
875
interface. This lets a request use a resource definition for the
 
876
previous version if it hasn't changed since then.
 
877
 
 
878
    >>> from zope.component import getSiteManager
 
879
    >>> from lazr.restful.interfaces import IWebServiceVersion
 
880
    >>> class ITestServiceRequestBeta(IWebServiceVersion):
 
881
    ...     pass
 
882
    >>> class ITestServiceRequest10(ITestServiceRequestBeta):
 
883
    ...     pass
 
884
    >>> class ITestServiceRequest20(ITestServiceRequest10):
 
885
    ...     pass
 
886
    >>> class ITestServiceRequest30(ITestServiceRequest20):
 
887
    ...     pass
 
888
    >>> sm = getSiteManager()
 
889
    >>> for marker, name in [(ITestServiceRequestBeta, 'beta'),
 
890
    ...                      (ITestServiceRequest10, '1.0'),
 
891
    ...                      (ITestServiceRequest20, '2.0'),
 
892
    ...                      (ITestServiceRequest30, '3.0')]:
 
893
    ...     sm.registerUtility(marker, IWebServiceVersion, name=name)
 
894
 
 
895
    >>> from lazr.restful.testing.webservice import FakeRequest
 
896
    >>> request = FakeRequest(version='beta')
 
897
 
 
898
 
850
899
Entry
851
900
-----
852
901
 
968
1017
    ...         self.base_price = base_price
969
1018
    ...         self.inventory_number = inventory_number
970
1019
 
971
 
Before we can continue, we must define a web service configuration
972
 
object. Each web service needs to have one of these registered
973
 
utilities providing basic information about the web service. This one
974
 
is just a dummy.
975
 
 
976
 
    >>> from lazr.restful.testing.helpers import TestWebServiceConfiguration
977
 
    >>> from zope.component import provideUtility
978
 
    >>> from lazr.restful.interfaces import IWebServiceConfiguration
979
 
    >>> class MyWebServiceConfiguration(TestWebServiceConfiguration):
980
 
    ...     active_versions = ["beta", "1.0", "2.0", "3.0"]
981
 
    ...     last_version_with_mutator_named_operations = "1.0"
982
 
    ...     first_version_with_total_size_link = "2.0"
983
 
    ...     code_revision = "1.0b"
984
 
    ...     default_batch_size = 50
985
 
    >>> provideUtility(MyWebServiceConfiguration(), IWebServiceConfiguration)
986
 
 
987
 
We must also set up the ability to create versioned requests. This web
988
 
service has four versions: 'beta', '1.0', '2.0', and '3.0'.  We'll
989
 
need a marker interface for every version, registered as a utility
990
 
under the name of the version.
991
 
 
992
 
Each version interface subclasses the previous version's
993
 
interface. This lets a request use a resource definition for the
994
 
previous version if it hasn't changed since then.
995
 
 
996
 
    >>> from zope.component import getSiteManager
997
 
    >>> from lazr.restful.interfaces import IWebServiceVersion
998
 
    >>> class ITestServiceRequestBeta(IWebServiceVersion):
999
 
    ...     pass
1000
 
    >>> class ITestServiceRequest10(ITestServiceRequestBeta):
1001
 
    ...     pass
1002
 
    >>> class ITestServiceRequest20(ITestServiceRequest10):
1003
 
    ...     pass
1004
 
    >>> class ITestServiceRequest30(ITestServiceRequest20):
1005
 
    ...     pass
1006
 
    >>> sm = getSiteManager()
1007
 
    >>> for marker, name in [(ITestServiceRequestBeta, 'beta'),
1008
 
    ...                      (ITestServiceRequest10, '1.0'),
1009
 
    ...                      (ITestServiceRequest20, '2.0'),
1010
 
    ...                      (ITestServiceRequest30, '3.0')]:
1011
 
    ...     sm.registerUtility(marker, IWebServiceVersion, name=name)
1012
 
 
1013
 
    >>> from lazr.restful.testing.webservice import FakeRequest
1014
 
    >>> request = FakeRequest(version='beta')
1015
 
 
1016
1020
Now we can turn a Book object into something that implements
1017
1021
IBookEntry.
1018
1022
 
1047
1051
      ...
1048
1052
    TypeError: 'IBookSet' isn't exported as an entry.
1049
1053
 
 
1054
 
1050
1055
Collection
1051
1056
----------
1052
1057