Merge pull request #56 from CiscoDevNet/feature-55-events-api

Feature 55 - Add Events API Support

Author: cmlccie

ciscosparkapi/__init__.py

@@ -16,6 +16,7 @@
 from past.builtins import basestring
 
 from .api.access_tokens import AccessTokensAPI as _AccessTokensAPI
+from .api.events import EventsAPI as _EventsAPI
 from .api.licenses import LicensesAPI as _LicensesAPI
 from .api.memberships import MembershipsAPI as _MembershipsAPI
 from .api.messages import MessagesAPI as _MessagesAPI
@@ -31,8 +32,8 @@
     ciscosparkapiException,
 )
 from .models import (
-    AccessToken, License, Membership, Message, Organization, Person, Role,
-    Room, Team, TeamMembership, Webhook, WebhookEvent, sparkdata_factory,
+    AccessToken, Event, License, Membership, Message, Organization, Person,
+    Role, Room, Team, TeamMembership, Webhook, WebhookEvent, sparkdata_factory,
 )
 from .restsession import (
     DEFAULT_SINGLE_REQUEST_TIMEOUT,
@@ -95,6 +96,8 @@ class CiscoSparkAPI(object):
 
                     :class:`roles <_RolesAPI>`
 
+                    :class:`events <_EventsAPI>`
+
                     :class:`access_tokens <_AccessTokensAPI>`
 
     """
@@ -187,6 +190,7 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
         self.access_tokens = _AccessTokensAPI(
             self.base_url, object_factory, timeout=single_request_timeout
         )
+        self.events = _EventsAPI(self._session, object_factory)
 
     @property
     def access_token(self):

ciscosparkapi/api/events.py

@@ -0,0 +1,153 @@
+# -*- coding: utf-8 -*-
+"""Cisco Spark Events API."""
+
+
+from __future__ import (
+    absolute_import,
+    division,
+    print_function,
+    unicode_literals,
+)
+
+from builtins import *
+
+from past.builtins import basestring
+
+from ..generator_containers import generator_container
+from ..restsession import RestSession
+from ..utils import (
+    check_type,
+    dict_from_items_with_values,
+)
+
+
+__author__ = "Chris Lunsford"
+__author_email__ = "[email protected]"
+__copyright__ = "Copyright (c) 2016-2018 Cisco and/or its affiliates."
+__license__ = "MIT"
+
+
+API_ENDPOINT = 'events'
+OBJECT_TYPE = 'event'
+
+
+class EventsAPI(object):
+    """Cisco Spark Events API.
+
+    Wraps the Cisco Spark Events API and exposes the API as native Python
+    methods that return native Python objects.
+
+    """
+
+    def __init__(self, session, object_factory):
+        """Initialize a new EventsAPI object with the provided RestSession.
+
+        Args:
+            session(RestSession): The RESTful session object to be used for
+                API calls to the Cisco Spark service.
+
+        Raises:
+            TypeError: If the parameter types are incorrect.
+
+        """
+        check_type(session, RestSession, may_be_none=False)
+
+        super(EventsAPI, self).__init__()
+
+        self._session = session
+        self._object_factory = object_factory
+
+    @generator_container
+    def list(self, resource=None, type=None, actorId=None, _from=None, to=None,
+             max=None, **request_parameters):
+        """List events.
+
+        List events in your organization. Several query parameters are
+        available to filter the response.
+
+        Note: `from` is a keyword in Python and may not be used as a variable
+        name, so we had to use `_from` instead.
+
+        This method supports Cisco Spark's implementation of RFC5988 Web
+        Linking to provide pagination support.  It returns a generator
+        container that incrementally yields all events returned by the
+        query.  The generator will automatically request additional 'pages' of
+        responses from Spark as needed until all responses have been returned.
+        The container makes the generator safe for reuse.  A new API call will
+        be made, using the same parameters that were specified when the
+        generator was created, every time a new iterator is requested from the
+        container.
+
+        Args:
+            resource(basestring): Limit results to a specific resource type.
+                Possible values: "messages", "memberships".
+            type(basestring): Limit results to a specific event type. Possible
+                values: "created", "updated", "deleted".
+            actorId(basestring): Limit results to events performed by this
+                person, by ID.
+            _from(basestring): Limit results to events which occurred after a
+                date and time, in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
+            to(basestring): Limit results to events which occurred before a
+                date and time, in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
+            max(int): Limit the maximum number of items returned from the Spark
+                service per request.
+            **request_parameters: Additional request parameters (provides
+                support for parameters that may be added in the future).
+
+        Returns:
+            GeneratorContainer: A GeneratorContainer which, when iterated,
+                yields the events returned by the Cisco Spark query.
+
+        Raises:
+            TypeError: If the parameter types are incorrect.
+            SparkApiError: If the Cisco Spark cloud returns an error.
+
+        """
+        check_type(resource, basestring)
+        check_type(type, basestring)
+        check_type(actorId, basestring)
+        check_type(_from, basestring)
+        check_type(to, basestring)
+        check_type(max, int)
+
+        params = dict_from_items_with_values(
+            request_parameters,
+            resource=resource,
+            type=type,
+            actorId=actorId,
+            _from=_from,
+            to=to,
+            max=max,
+        )
+
+        if _from:
+            params["from"] = params.pop("_from")
+
+        # API request - get items
+        items = self._session.get_items(API_ENDPOINT, params=params)
+
+        # Yield event objects created from the returned items JSON objects
+        for item in items:
+            yield self._object_factory(OBJECT_TYPE, item)
+
+    def get(self, eventId):
+        """Get the details for an event, by event ID.
+
+        Args:
+            eventId(basestring): The ID of the event to be retrieved.
+
+        Returns:
+            Event: A event object with the details of the requested room.
+
+        Raises:
+            TypeError: If the parameter types are incorrect.
+            SparkApiError: If the Cisco Spark cloud returns an error.
+
+        """
+        check_type(eventId, basestring, may_be_none=False)
+
+        # API request
+        json_data = self._session.get(API_ENDPOINT + '/' + eventId)
+
+        # Return a room object created from the response JSON data
+        return self._object_factory(OBJECT_TYPE, json_data)

ciscosparkapi/models/__init__.py

@@ -12,6 +12,7 @@
 from collections import defaultdict
 
 from .access_token import AccessTokenBasicPropertiesMixin
+from .event import EventBasicPropertiesMixin
 from .license import LicenseBasicPropertiesMixin
 from .membership import MembershipBasicPropertiesMixin
 from .message import MessageBasicPropertiesMixin
@@ -36,6 +37,10 @@ class AccessToken(SparkData, AccessTokenBasicPropertiesMixin):
     """Cisco Spark Access-Token data model."""
 
 
+class Event(SparkData, EventBasicPropertiesMixin):
+    """Cisco Spark Event data model."""
+
+
 class License(SparkData, LicenseBasicPropertiesMixin):
     """Cisco Spark License data model."""
 
@@ -82,6 +87,7 @@ class WebhookEvent(SparkData, WebhookEventBasicPropertiesMixin):
 sparkdata_models = defaultdict(
     lambda: SparkData,
     access_token=AccessToken,
+    event=Event,
     license=License,
     membership=Membership,
     message=Message,

ciscosparkapi/models/event.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""Cisco Spark Event data model."""
+
+
+from __future__ import (
+    absolute_import,
+    division,
+    print_function,
+    unicode_literals,
+)
+
+from builtins import *
+
+from .sparkdata import SparkData
+
+
+__author__ = "Chris Lunsford"
+__author_email__ = "[email protected]"
+__copyright__ = "Copyright (c) 2016-2018 Cisco and/or its affiliates."
+__license__ = "MIT"
+
+
+class EventBasicPropertiesMixin(object):
+    """A mixin for :class:`SparkData` classes."""
+
+    @property
+    def id(self):
+        """Event ID."""
+        return self._json_data.get('id')
+
+    @property
+    def resource(self):
+        """The event resource type (`messagess`, `memberships`)."""
+        return self._json_data.get('resource')
+
+    @property
+    def type(self):
+        """The event type (`created`, `updated`, `deleted`)."""
+        return self._json_data.get('type')
+
+    @property
+    def actorId(self):
+        """The ID of the person that performed this event."""
+        return self._json_data.get('actorId')
+
+    @property
+    def created(self):
+        """The date and time the event was performed."""
+        return self._json_data.get('created')
+
+    @property
+    def data(self):
+        """The event resource data."""
+        return SparkData(self._json_data.get('data'))

ciscosparkapi/models/webhook_event.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark Access-Token data model."""
+"""Cisco Spark Webhook-Event data model."""
 
 
 from __future__ import (
@@ -91,30 +91,5 @@ def actorId(self):
 
     @property
     def data(self):
-        """The data for the resource that triggered the webhook.
-
-        For example, if you registered a webhook that triggers when messages
-        are created (i.e. posted into a room) then the data property will
-        contain the JSON representation for a message resource.
-
-        Note:  That not all of the details of the resource are included in the
-        data object.  For example, the contents of a message are not included.
-        You would need to request the details for the message using the message
-        'id' (which is in the data object) and the
-        `CiscoSparkAPI.messages.get()` method.
-
-        """
-        if self._data is None and self._json_data.get('data'):
-            if self.resource == "memberships":
-                self._data = Membership(self._json_data.get('data'))
-
-            elif self.resource == "messages":
-                self._data = Message(self._json_data.get('data'))
-
-            elif self.resource == "rooms":
-                self._data = Room(self._json_data.get('data'))
-
-            else:
-                self._data = SparkData(self._json_data.get('data'))
-
-        return self._data
+        """The data for the resource that triggered the webhook."""
+        return SparkData(self._json_data.get('data'))

docs/user/api.rst

@@ -101,6 +101,14 @@ roles
 .. autoclass:: ciscosparkapi.api.roles.RolesAPI()
 
 
+.. _events:
+
+events
+-----
+
+.. autoclass:: ciscosparkapi.api.events.EventsAPI()
+
+
 .. _access_tokens:
 
 access_tokens
@@ -232,6 +240,15 @@ Role
     :inherited-members:
 
 
+.. _Event:
+
+Event
+-----
+
+.. autoclass:: Event()
+    :inherited-members:
+
+
 .. _Access Token:
 
 Access Token

docs/user/quickstart.rst

@@ -239,6 +239,10 @@ structure is provided here.
 |                       |                         +-------------------------------------+
 |                       |                         | :meth:`~RolesAPI.create`            |
 +-----------------------+-------------------------+-------------------------------------+
+|                       | :ref:`events`           | :meth:`~EventsAPI.list`             |
+|                       |                         +-------------------------------------+
+|                       |                         | :meth:`~EventsAPI.get`              |
++-----------------------+-------------------------+-------------------------------------+
 |                       | :ref:`access_tokens`    | :meth:`~AccessTokensAPI.get`        |
 |                       |                         +-------------------------------------+
 |                       |                         | :meth:`~AccessTokensAPI.refresh`    |