Google App Engine Api和端点版本控制

Question

I'm having some troubles finding proper way of handling multiple versions of remote.Service api in my application.

class MyService(Service):
   @endpoints.method(
        endpoints.ResourceContainer(
            something=protorpc.messages.StringField(1, required=True),
        ),
        message_types.VoidMessage,
    )
    def do_stuff(self, request):
        ... implement do_stuff ...

class MyBetterService(MyService):
    @endpoints.method(
        endpoints.ResourceContainer(
            some_other_name=protorpc.messages.StringField(1, required=True),
        ),
        message_types.VoidMessage,
    )
    def do_stuff(self, request):
        # ...other way of doing stuff
        return message_types.VoidMessage()

When trying to make libraries i got this error:

protorpc.remote.ServiceDefinitionError: Do not use method decorator when overloading remote method do_stuff on service MyBetterService.

Is there way for overriding method in next version of API?

Overridden method may take other request parameters?

Is there possibility of adding only one endpoint in different version to existing api?

Answer 1

The endpoints service classes are written such that once you define a public interface method you may not alter them in sub-classes. Normally you should not define a new API version of a class as a sub-class unless it an exact super-set the interface of the super class.

In the case where the new version is a super-set you may use redefine interface methods which will automatically inherit the attributes of the parent method. For example:

class MyService(Service):
   @endpoints.method(
        endpoints.ResourceContainer(
            something=protorpc.messages.StringField(1, required=True),
        ),
        message_types.VoidMessage,
    )
    def do_stuff(self, request):
        ... implement do_stuff ...

class MyBetterService(MyService):
    def do_stuff(self, request):
        # ...other way of doing stuff
        return message_types.VoidMessage()

   @endpoints.method(
        endpoints.ResourceContainer(
            something=protorpc.messages.IntegerField(1, required=True),
        ),
        message_types.VoidMessage,
    )
    def do_more_stuff(self, request):
        ... implement do_more_stuff ...

There is no way to change the input-type for do_stuff() .

In practice new API versions ought to be treated the same as a new API and have an independent Service class definition. Think of an API really as an interface. While two classes should not share a base class with common API method defintions, it does not mean that two classes may now share a common set of functional classes.

When I've built services I've implemented the API versions as separate classes, even if I've had to duplicate many of the method signatures. Underneath the service, however, I implemented a system of objects that perform the same actions entirely independently of the interface and API message types. This allows two API versions to share significant parts of the implementation.

For example:

from mysystem import MyImplementation

class MyService(Service):
   @endpoints.method(
        endpoints.ResourceContainer(
            something=protorpc.messages.StringField(1, required=True),
        ),
        message_types.VoidMessage,
    )
    def do_stuff(self, request):
      MyImplementation.do_stuff(request.something)

class MyBetterService(Service):
   @endpoints.method(
        endpoints.ResourceContainer(
            something=protorpc.messages.IntegerField(1, required=True),
        ),
        message_types.VoidMessage,
    )
    def do_stuff(self, request):
      MyImplementation.do_stuff(self.lookup_string(request.something))

In this model, I think of the API as being responsible for marshaling information between the service interface and the actual underlying system, rather than an actual implementation.

While explicitly copying each method for each new implementation might seem like a lot of work, in practice it's usually a very small portion of what your overall service is supposed to do.