Cloud Endpoints and App Engine

Question

I've just started on Google Cloud and I'm creating an iOS app to interact with Google Cloud services via a mobile backend. I'm using Python to write the backend for App Engine. I've gone through the tutorials in creating an API based on endpoints - but I have a question.

Do I have to create a Cloud Endpoints API, and then an app on App Engine? Basically, I want to be able to register accounts on my iOS app, call an API which then makes use of Google Datastore to store the account details. From looking at the tutorials (both the cloud endpoints one and then the guestbook one), am I meant to expose Google Datastore, cloud storage etc. within the endpoints api? Or does that link into another app where that is all done?

Sorry if this sounds a bit silly, but I just want to make sure!

Thanks in advance.

Answer 1

In a nutshell, your Cloud Endpoints API is your application. Some of the documentation regarding Cloud Endpoints can be a bit confusing (or vague), but on the server side it's essentially a bunch of Python decorators or Java annotations that allow you to expose your application logic as a REST API.

I find the Java implementation of Cloud Endpoints more intuitive than the Python one, which requires a bit more work to (de-)serialise your objects. You could look at endpoints_proto_datastore.ndb.EndpointsModel which might take some of the boilerplate stuff out of the equation (defining messages).

Essentially, when you write your API, each endpoint maps to a python function. Inside that function you can do what you like, but typically it will be either:

1. Deserialise your POSTed JSON, validate it, and write some entities to Datastore (or Cloud SQL, BigTable, wherever).

2. Read one or more entities from Datastore and serialize them to JSON and return them to the client.

For example, you might define your API (the whole collection of endpoint functions) as

@endpoints.api(name='cafeApi', version='v1', description='Cafe API', audiences=[endpoints.API_EXPLORER_CLIENT_ID])
class CafeApi(remote.Service):
    # endpoints here

For example, you might have an endpoint to get nearby cafes:

@endpoints.method(GEO_RESOURCE, CafeListResponse, path='cafes/nearby', http_method='GET', name='cafes.nearby')
def get_nearby_cafes(self, request):
    """Get cafes close to specified lat,long"""
    cafes = list()
    for c in search.get_nearby_cafes(request.lat, request.lon):
        cafes.append(c.response_message())

    return CafeListResponse(cafes=cafes)

A couple of things to highlight here. With the Python Endpoints implementation, you need to define your resource and message classes - these are used to encapsulate request data and response bodies.

So, in the above example, GEO_RESOURCE encapsulates the fields required to make a GeoPoint (so we can search by location using Search API, but you might just search Datastore for Cafes with a 5-star rating):

    GEO_RESOURCE = endpoints.ResourceContainer(
        message_types.VoidMessage,
        lat=messages.FloatField(1, required=True),
        lon=messages.FloatField(2, required=True)
    )

and the CafeListResponse would just encapsulate a list of CafeResponse objects (with Cloud Endpoints you return a single object):

class CafeListResponse(messages.Message):
    locations = messages.MessageField(CafeResponse, 1, required=False, repeated=True)

where the CafeResponse is the message that defines how you want your objects (typically Datastore entities) serialised by your API. eg,

class LocationResponse(messages.Message):
    id = messages.StringField(1, required=False)
    coordinates = messages.MessageField(GeoMessage, 3, required=True)
    name = messages.StringField(4, required=False)

With that endpoint signature, you can access it via an HTTP GET at /cafeApi/v1/cafes/nearby?lat=...&lon=... or via, say, the Javascript API client with `cafeApi.cafes.nearby(...).

Personally, I found Flask a bit more flexible with working with Python to create a REST API.