Merge pull request #1533 from turt2live/travis/as/general

General/small improvements to the application service API specification

api/application-service/application_service.yaml

@@ -32,6 +32,10 @@ paths:
       description: |-
         This API is called by the homeserver when it wants to push an event
         (or batch of events) to the application service.
+
+        Note that the application service should distinguish state events
+        from message events via the presence of a ``state_key``, rather than
+        via the event type.
       operationId: sendTransaction
       parameters:
         - in: path
@@ -44,7 +48,7 @@ paths:
           x-example: "35"
         - in: body
           name: body
-          description: A list of events
+          description: A list of events.
           schema:
             type: object
             example: {

specification/application_service_api.rst

@@ -1,4 +1,5 @@
 .. Copyright 2016 OpenMarket Ltd
+.. Copyright 2018 New Vector Ltd
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -39,7 +40,7 @@ This version of the specification is generated from
 Application Services
 --------------------
 Application services are passive and can only observe events from a given
-homeserver. They can inject events into rooms they are participating in.
+homeserver (HS). They can inject events into rooms they are participating in.
 They cannot prevent events from being sent, nor can they modify the content of
 the event being sent. In order to observe events from a homeserver, the
 homeserver needs to be configured to pass certain types of traffic to the
@@ -68,7 +69,13 @@ Registration
 Application services register "namespaces" of user IDs, room aliases and room IDs.
 These namespaces are represented as regular expressions. An application service
 is said to be "interested" in a given event if one of the IDs in the event match
-the regular expression provided by the application service. An application
+the regular expression provided by the application service, such as the room having
+an alias or ID in the relevant namespaces. Similarly, the application service is
+said to be interested in a given event if one of the application service's namespaced
+users is the target of the event, or is a joined member of the room where the event
+occurred.
+
+An application
 service can also state whether they should be the only ones who
 can manage a specified namespace. This is referred to as an "exclusive"
 namespace. An exclusive namespace prevents humans and other application
@@ -222,7 +229,8 @@ need to be able to adjust the ``origin_server_ts`` value to do this.
 
 Inputs:
  - Application service token (``as_token``)
- - Desired timestamp
+ - Desired timestamp (in milliseconds since the unix epoch)
+
 Notes:
  - This will only apply when sending events.