• What is Discovery?
• Consuming Discovery-based APIs with google-api-python-client
• Creating Discovery based APIs

• An API:
  • APIs directory of all APIs supported by the Discovery Service
  • In depth machine-readable description of each API
  • Self-describing
• A format:
  • OAuth scopes
  • Object and field schemas
  • Resources and methods
  • Request paths, parameters and payloads
  • Inline documentation
  • ...

• Provides API design guidance
• Well-defined specification; common shared infrastructure
• Schemas, methods, auth; all pieces needed to construct a call
• Language neutral

• Client Libraries Galore
  • Python: google-api-python-client
  • JavaScript: google-api-javascript-client
  • Java: google-api-java-client
  • Objective C: google-api-objectivec-client
  • Ruby: google-api-ruby-client
  • Go: google-api-go-client
  • PHP: google-api-php-client
  • Node.js: google-api-nodejs-client
  • Dart: google-api-dart-client
  • .NET: google-api-dotnet-client
  • GWT: gwt-google-apis
  • ...

>>> from apiclient.discovery import build
>>> service = build('urlshortener', 'v1')
>>> result = service.url().get(shortUrl='http://goo.gl/cyY1U').execute()
>>> result
{u'id': u'http://goo.gl/cyY1U',
 u'kind': u'urlshortener#url',
 u'longUrl': u'https://pycon2013-discovery.appspot.com/',
 u'status': u'OK'}

from apiclient.http import HttpRequest
DISCOVERY_URI = ('https://www.googleapis.com/discovery/v1/apis/'
                 '{api}/{apiVersion}/rest')

def build(serviceName,
          version,
          http=None,
          discoveryServiceUrl=DISCOVERY_URI,
          developerKey=None,
          model=None,
          requestBuilder=HttpRequest):
  ...
  return build_from_document(content, base=discoveryServiceUrl, http=http,
      developerKey=developerKey, model=model, requestBuilder=requestBuilder)

def build_from_document(
    service,
    base=None,
    http=None,
    developerKey=None,
    model=None,
    requestBuilder=HttpRequest):
  ...
  return Resource(http=http, baseUrl=base, model=model,
                  developerKey=developerKey, requestBuilder=requestBuilder,
                  resourceDesc=service, rootDesc=service, schema=schema)

  def _add_basic_methods(self, resourceDesc, rootDesc, schema):
      ...
      for methodName, methodDesc in resourceDesc['methods'].iteritems():
        fixedMethodName, method = createMethod(
            methodName, methodDesc, rootDesc, schema)
        self._set_dynamic_attr(fixedMethodName,
                                 method.__get__(self, self.__class__))
        ...

from protorpc import messages


class Task(messages.Message):
  name = messages.StringField(1, required=True)
  owner = messages.StringField(2)

• Use protorpc to talk to Google's API infrastructure
• Strict field types help in generating backend API config

"Task": {
  "id": "Task",
  "properties": {
    "name": {
      "required": true,
      "type": "string"
    },
    "owner": {
      "type": "string"
    }
  },
  "type": "object"
}

from google.appengine.ext import endpoints
from protorpc import remote

@endpoints.api(name='tasks', version='v1',
                description='API for Task Management')
class TaskApi(remote.Service):

  @endpoints.method(Task, Task,
                      name='task.insert', path='task')
  def insert_task(self, request):
    ...
    return request

• The @endpoints.api decorator provides API level metadata
• The @endpoints.method decorator helps determine method specific metadata

"descriptor": {
  "methods": {
    "TaskApi.insert_task": {
      "request": {
        "$ref": "Task"
      },
      "response": {
        "$ref": "Task"
      }
    },
  ...

"tasks.task.insert": {
  ...
  "httpMethod": "POST",
  "path": "task",
  "request": {
    "body": "autoTemplate(backendRequest)",
    "bodyName": "resource"
  },
  "response": {
    "body": "autoTemplate(backendResponse)",
    "bodyName": "resource"
  },
  "rosyMethod": "TaskApi.insert_task"

• Many more fields in Discovery than required to describe service
• Backend Centric API Configuration
• Discovery is self-documenting, meant to be consumed by intelligent clients

  ...
  @endpoints.method(Task, Task,
                      name='task.get', path='task/{name}',
                      http_method='GET')
  def get_task(self, request):
    ...
    return Task(...)

"tasks.task.get": {
  ...
  "httpMethod": "GET",
  "path": "task/{name}",
  "request": {
    "body": "empty",
    "parameterOrder": ["name"],
    "parameters": {
      "name": {
        "required": true,
        "type": "string"
      },
      "owner": {
        "type": "string"
        ...

    "get": {
     "id": "tasks.task.get",
     "path": "task/{name}",
     "httpMethod": "GET",
     "parameters": {
      "name": {
       "type": "string",
       "required": true,
       "location": "path"
      },
      ...
     "response": {
       "$ref": "Task"
     }

>>> from apiclient.discovery import build
>>> DISCOVERY_URI = ('https://pycon2013-discovery.appspot.com/_ah/api/discovery/'
...                  'v1/apis/{api}/{apiVersion}/rest')
>>> service = build('tasks', 'v1',
                    discoveryServiceUrl=DISCOVERY_URI)
>>> body = {'name': 'Stop Talking', 'owner': 'Danny'}
>>> result = service.task().insert(body=body).execute()
>>> result
{u'name': u'Stop Talking',
 u'owner': u'Danny'}

• Build your own API
• Check out a more advanced API
• Check out the Python Client Library
• Google Developers Live Endpoints Video
• APIs Explorer for this demo
• Slides for this talk