diff --git a/inbox/rest.xml b/inbox/rest.xml index 255437a9..b934fda5 100644 --- a/inbox/rest.xml +++ b/inbox/rest.xml @@ -1,708 +1,708 @@ - - -%ents; -]> - - -
- REST with XMPP - This specification defines how the Representational State Transfer (REST) - architectural style can be applied to an XMPP overlay network. It specifies - an XMPP protocol extension for accessing resources and transporting resource metadata and XML-REST encoded - requests and responses between two XMPP entities. - - This XMPP Extension Protocol is copyright (c) 1999 - 2014 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - xxxx - ProtoXEP - Standards Track - Standards - Council - - XMPP Core - - - - NOT_YET_ASSIGNED - - Alexander - Stanik - alexander.stanik@tu-berlin.de - http://www.cit.tu-berlin.de/ - - - 0.0.1 - 2015-05-11 - as -

First draft.

 - -
- -

Representational State Transfer (REST) is an architectural style that is a coordinated - set of constraints which also apply to the web. It aims at simplifying component implementations, reducing - the complexity of distributed software elements, improving the performance, and increasing the - scalability. In relation to the definition of a RESTful application programming interface (API) - the uniform interface constraint is of high importance. It simplifies and decouples the architecture - and makes REST components independent. The constraints for a uniform interface can be reduced to: - the identification of resources, the self-descriptive representation of resources, and the - self-descriptive manipulation of resources.

-

REST systems typically communicate over the Hypertext Transfer Protocol (HTTP) and are gaining - large acceptance due to its - growing support and its simplicity for implementation. RESTful web services - are in this context a simpler alternative to &w3soap; and WSDL-based Web services which are specified - for the use with XMPP - in &xep0072; and also a more powerful alternative to &xmlrpc; which are specified as XMPP extension - in &xep0009;.

-

The &xep0332; allows for designing REST services in the context of XMPP, but requires an implementation - of both protocols: XMPP and HTTP. Furthermore, HTTP was selected in the past because of its - degree of popularity, but has some drawbacks like the lack of discoverability of services. - The REST with XMPP extension is a powerful protocol for cloud services that has - several advantages in contrast to the traditional HTTP-based REST approach:

-
    -
  1. services are discoverable and explorable,
    2. -
  2. asynchronous invocation can be performed in parallel,
    3. -
  3. generation of clients on the fly based on the capabilities of resources, and
    4. -
  4. multiple input and output types definitions are possible.
    5. -
-

The REST with XMPP protocol makes use of the &IQ; stanza in order to enable access, to create, to delete, - or to modify resources within a XMPP network overlay. This specification defines two XML Schema files: - one for exploring the capabilities of a resource and one for performing actions on a resource.

- - -

The author has designed the REST with XMPP protocol with the following requirements in mind:

- - - -

In order to explore the capabilities of a resource, the &IQ; stanza type "get" have to be used. The returned - &IQ; stanza is either of type "error" or "result". If it is of type "result", the returned content has to be - complied with the xwadl schema of this specification. The xwadl schema has been designed for providing a machine - process-able description of a resource. It was inspired by the Web Application Description Language (WADL) - standard delivered by the World Wide Web Consortium (W3C).

-

An &IQ; stanza of type "get" is returning an &IQ; stanza of type "result" that describes all actions that the - requesting party can perform. The following example shows an exploration of a cloud provider's REST based - interface for handling compute services.

- - - - - ]]> -

In order to explore a resource, only the path to a resource is required. The counter party has to - answer of such a request with a response that exposes all possible actions which can be performed on the - resource located at the specified path. The following example illustrates a response that exposes all - actions for this resource.

- - - - - Use one of the following actions to manage your compute instances! - - - - - - - - - - - - - - - - - - - - - - - ]]> -

This response exposes two methods that can be performed on the - resource located at "/compute". The first method "create" can be used to create one or - more virtual machines (VM). This method has three input parameters in its request and one output - parameter in its response. If a client would like to perform this method, at least only a link to - the location of an image is required. The other two parameters are optional. The server will respond to this - method with a list of links to the instantiated VMs. A detailed example of how to access this method is - illustrated in the Resource Access section.

-

The following subsections describe each component of a xwadl document in detail.

- -

The "resource_type" element forms the root of a xwadl document and MAY comprises the following - sub-elements: "doc", "grammars", and "method"

- - -

Each xwadl-defined element down to the "param" can have one or more child "doc" elements that - can be used to document that element. The doc element has "title" attributes which is a short plain - text description of the element being documented. The "doc" element can have mixed content - and may contain text and zero or more child elements.

- - -

The "grammars" element acts as a container for definitions of the format of data exchanged - during execution of the protocol described by the xwadl document and SHOULD be according to the - XML Schema definition.

- - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - -

A method element describes the specific actions that can be performed on a resource targeted - by the "path" attribute of the "resource_type" element. - A method element is a child of a "resource_type" element and has a "name" attribute - that identifies this method.

-

Additionally, each "method" MUST have one "request" and one "response" element - which can be empty or be used to expose the optional parameters that this method can execute.

- - -

The "request" and the "response" element are according to the xwadl schema of type "call". They are - identical by definition and describe the input and output data for accessing a resource.

-
    -
  • A request describes the input to the method as a collection of parameters.
    • -
  • A response describes the output to the method as a collection of parameters.
    • -
-

Both elements describe the information to be included when applying a method to a resource. - Both elements have no attributes and may contain one or more "param" elements as child elements.

- - -

A "param" element describes a parameterized component of its parent element (either a request or a - response). It can be identified by its "name" attribute and MUST have a minimum of one "option" element - that defines one of a set of possible - values for the parameter. In order to parameterize a component, the "param" element SHOULD specify - a combination of the following attributes:

-
    -
  • The name attribute specifies the name of the parameter and is a required attribute.
    • -
  • The default attribute specifies an OPTIONAL default value that is applied if this - parameter is not used while accessing a resource. If this attribute is specified, the overall parameter - element is optional when accessing a resource.
    • -
  • The required attribute is an OPTIONAL element and can be either false or true (default is false). - It indicates whether the parameter is required to be present or not.
    • -
  • The repeating attribute is an OPTIONAL element and can be either false or true (default is false). - It indicates whether the parameter is single valued or may have multiple values.
    • -
-

Some combinations of attributes do not make sense, e.g. the specification of "default=?" and "repeating=true", - and SHOULD be considered application specific.

- - -

An "option" element defines one of a set of possible types, representations, link type, or also values - for the parameter. An "option" element MUST have one of the following attributes:

-
- -
type
-
-

The "type" attribute indicates one possible type of the parameter as an XML qualified name, - defaults to xs:string. It SHOULD specify the type of a single optional value. Multiple options - with the same type but different values SHOULD specify a set of possible values which are - acceptable as input for the parent parameter.

-
- - -
mediaType
-
-

The "mediaType" attribute indicates that the parent parameter acts as a media type selector - for requests or responses. The value of the attribute is the media type that is expected. If - a representation of an OPTIONAL media type is exposed, this representation can act as a - template for manipulating a resource.

-
- - -
link
-
-

The "link" attribute is used to identify links to resources. It can have the value local, remote, - or list. A local link links to another resource located at the same server entity. A remote link links to - a resource located at another server entity anywhere in the XMPP network overlay. A link with a - list value indicates a list of remote links that can be used for discovery or linking to a set - of resources.

-
- -
- - - -

In order to access a resource, the &IQ; stanza type "set" has to be used. The returned - &IQ; stanza is either of type "error" or "result". If it is of type "result", the returned content has to be - complied with the xml-rest schema of this specification. The xml-rest schema has been designed - for providing a xml-rest encoded payload for accessing a resource. - An &IQ; stanza MUST NOT contain more than one method element with one request and one response. - The following example illustrates how the create method of the previous example is requested. - Here, the client requests three VMs which are based on an image that is available as resource - on the client's side.

- - - - - - - - requester@company-b.com/rest-client - /images/myLinuxImage - - - - 3 - - - - - - - - - - - ]]> -

In order to make sure that both parties have a common understanding, the requester specifies also - the expected responds type which has been exposed during the exploration step. The counter party has to - answer such a request with the same request element and an extended complitation of the response - element as illustrated in the example below. -

- - - - - - - - requester@company-b.com/rest-client - /images/myLinuxImage - - - - 3 - - - - - - - dc1.company-a.com/openstack - requester/vms/vm1 - - - dc2.company-a.com/openstack - requester/vms/vm02 - - - dc3.company-a.com/openstack - requester/vms/vm003 - - - - - - - - ]]> -

The following subsections describe each component of a xml-rest document in detail.

- -

The "resource" element forms the root of an xml-rest document and MUST comprise only a - single "method" sub-element. In contrast to the xwadl description, no further documentation or grammers - are possible in order to keep the number of bytes as low as possible. - In order to specify the resource to access, the "path" attribute is required.

- - -

The "method" element MUST have one request element and one response element. Additionally, the - "name" attribute is required in order to identify the action that has to be performed on the resource.

- - -

The "request" and the "response" element are according to the xml-rest schema of type "call". They are - identical by definition and including the information for applying the method of a resource. - Both elements have no attributes and may contain one or more "param" elements as child elements.

-
    -
  • A request includes the input data to the method as a collection of parameters.
    • -
  • A response includes the output data to the method as a collection of parameters.
    • -
- - -

Each "param" element has a "name" attribute to identify the parameter and a single sub-element - that includes the data. Possible sub-elements are value, representation, link, or resourceList.

- - -

The "value" element has a "type" attribute that specifies the type of the value.

- - -

The "representation" element has a "mediaType" attribute that specifies the media type of the representation.

- - -

A "link" element or a "resourceList" element have no attributes. While a link targets to a single local - or remote location, a resource list is a set of links which are targeting to any resource in an XMPP - overlay network. A link can be expressed in two forms: as XMPP resource link with a "to" - (e.g. <to>requester@company-b.com/rest-client</to>) and a "path" (e.g. - <path>/images/myLinuxImage</path>) element - or as URI (<uri>xmpp://requester@company-b.com/rest-client?/images/myLinuxImage</uri>).

- - - - - -

The REST with XMPP protocol enables a multi-dimensional resource placement. The following examples show - how different resources can be placed within a single server entity:

- - - ... - - - ]]> - - - ... - - - ]]> - - - ... - - - ]]> - - - ... - - - ]]> - - - ... - - - ]]> -

All examples above are accessing different resources. A variation of the path attribute of the resource - element would also combine the presented JIDs and referring to different resources. - Further examples are possible to show how different resources can be located at a single server entity.

- - - -

If an entity supports the REST with XMPP protocol, it SHOULD advertise that fact in response to &xep0030; information ("diso#info") requests by returning an identity of "automation/rest" and a feature of "jabber:iq:rest":

- - - - ]]> - - - - - - - ]]> - - -

Determining when and how a resource can be accessed or modified based on permissions or - rights are considered outside the scope of this document. Although such mechanisms SHOULD be - considered specifically to the application and/or implementation of this document, - future specifications may address these concerns.

- - -

REQUIRED.

- - - -

The ®ISTRAR; includes 'urn:xmpp:rest:xwadl' and 'urn:xmpp:rest:xml' in its registry of protocol namespaces.

- - -

The XMPP Registrar includes a Service Discovery type of "rest" within the "automation" category in its registry of service discovery identities.

- - - - - - - - - - - The protocol documented by this schema is defined in - XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - - - - - - - The protocol documented by this schema is defined in - XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - + + +%ents; +]> + + +
+ REST with XMPP + This specification defines how the Representational State Transfer (REST) + architectural style can be applied to an XMPP overlay network. It specifies + an XMPP protocol extension for accessing resources and transporting resource metadata and XML-REST encoded + requests and responses between two XMPP entities. + + This XMPP Extension Protocol is copyright (c) 1999 - 2014 by the XMPP Standards Foundation (XSF). + Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. + ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## + In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. + This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). + + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + + + + NOT_YET_ASSIGNED + + Alexander + Stanik + alexander.stanik@tu-berlin.de + http://www.cit.tu-berlin.de/ + + + 0.0.1 + 2015-05-11 + as +

First draft.

 + +
+ +

Representational State Transfer (REST) is an architectural style that is a coordinated + set of constraints which also apply to the web. It aims at simplifying component implementations, reducing + the complexity of distributed software elements, improving the performance, and increasing the + scalability. In relation to the definition of a RESTful application programming interface (API) + the uniform interface constraint is of high importance. It simplifies and decouples the architecture + and makes REST components independent. The constraints for a uniform interface can be reduced to: + the identification of resources, the self-descriptive representation of resources, and the + self-descriptive manipulation of resources.

+

REST systems typically communicate over the Hypertext Transfer Protocol (HTTP) and are gaining + large acceptance due to its + growing support and its simplicity for implementation. RESTful web services + are in this context a simpler alternative to &w3soap; and WSDL-based Web services which are specified + for the use with XMPP + in &xep0072; and also a more powerful alternative to &xmlrpc; which are specified as XMPP extension + in &xep0009;.

+

The &xep0332; allows for designing REST services in the context of XMPP, but requires an implementation + of both protocols: XMPP and HTTP. Furthermore, HTTP was selected in the past because of its + degree of popularity, but has some drawbacks like the lack of discoverability of services. + The REST with XMPP extension is a powerful protocol for cloud services that has + several advantages in contrast to the traditional HTTP-based REST approach:

+
    +
  1. services are discoverable and explorable,
    2. +
  2. asynchronous invocation can be performed in parallel,
    3. +
  3. generation of clients on the fly based on the capabilities of resources, and
    4. +
  4. multiple input and output types definitions are possible.
    5. +
+

The REST with XMPP protocol makes use of the &IQ; stanza in order to enable access, to create, to delete, + or to modify resources within a XMPP network overlay. This specification defines two XML Schema files: + one for exploring the capabilities of a resource and one for performing actions on a resource.

+ + +

The author has designed the REST with XMPP protocol with the following requirements in mind:

+ + + +

In order to explore the capabilities of a resource, the &IQ; stanza type "get" have to be used. The returned + &IQ; stanza is either of type "error" or "result". If it is of type "result", the returned content has to be + complied with the xwadl schema of this specification. The xwadl schema has been designed for providing a machine + process-able description of a resource. It was inspired by the Web Application Description Language (WADL) + standard delivered by the World Wide Web Consortium (W3C).

+

An &IQ; stanza of type "get" is returning an &IQ; stanza of type "result" that describes all actions that the + requesting party can perform. The following example shows an exploration of a cloud provider's REST based + interface for handling compute services.

+ + + + + ]]> +

In order to explore a resource, only the path to a resource is required. The counter party has to + answer of such a request with a response that exposes all possible actions which can be performed on the + resource located at the specified path. The following example illustrates a response that exposes all + actions for this resource.

+ + + + + Use one of the following actions to manage your compute instances! + + + + + + + + + + + + + + + + + + + + + + + ]]> +

This response exposes two methods that can be performed on the + resource located at "/compute". The first method "create" can be used to create one or + more virtual machines (VM). This method has three input parameters in its request and one output + parameter in its response. If a client would like to perform this method, at least only a link to + the location of an image is required. The other two parameters are optional. The server will respond to this + method with a list of links to the instantiated VMs. A detailed example of how to access this method is + illustrated in the Resource Access section.

+

The following subsections describe each component of a xwadl document in detail.

+ +

The "resource_type" element forms the root of a xwadl document and MAY comprises the following + sub-elements: "doc", "grammars", and "method"

+ + +

Each xwadl-defined element down to the "param" can have one or more child "doc" elements that + can be used to document that element. The doc element has "title" attributes which is a short plain + text description of the element being documented. The "doc" element can have mixed content + and may contain text and zero or more child elements.

+ + +

The "grammars" element acts as a container for definitions of the format of data exchanged + during execution of the protocol described by the xwadl document and SHOULD be according to the + XML Schema definition.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + +

A method element describes the specific actions that can be performed on a resource targeted + by the "path" attribute of the "resource_type" element. + A method element is a child of a "resource_type" element and has a "name" attribute + that identifies this method.

+

Additionally, each "method" MUST have one "request" and one "response" element + which can be empty or be used to expose the optional parameters that this method can execute.

+ + +

The "request" and the "response" element are according to the xwadl schema of type "call". They are + identical by definition and describe the input and output data for accessing a resource.

+
    +
  • A request describes the input to the method as a collection of parameters.
    • +
  • A response describes the output to the method as a collection of parameters.
    • +
+

Both elements describe the information to be included when applying a method to a resource. + Both elements have no attributes and may contain one or more "param" elements as child elements.

+ + +

A "param" element describes a parameterized component of its parent element (either a request or a + response). It can be identified by its "name" attribute and MUST have a minimum of one "option" element + that defines one of a set of possible + values for the parameter. In order to parameterize a component, the "param" element SHOULD specify + a combination of the following attributes:

+
    +
  • The name attribute specifies the name of the parameter and is a required attribute.
    • +
  • The default attribute specifies an OPTIONAL default value that is applied if this + parameter is not used while accessing a resource. If this attribute is specified, the overall parameter + element is optional when accessing a resource.
    • +
  • The required attribute is an OPTIONAL element and can be either false or true (default is false). + It indicates whether the parameter is required to be present or not.
    • +
  • The repeating attribute is an OPTIONAL element and can be either false or true (default is false). + It indicates whether the parameter is single valued or may have multiple values.
    • +
+

Some combinations of attributes do not make sense, e.g. the specification of "default=?" and "repeating=true", + and SHOULD be considered application specific.

+ + +

An "option" element defines one of a set of possible types, representations, link type, or also values + for the parameter. An "option" element MUST have one of the following attributes:

+
+ +
type
+
+

The "type" attribute indicates one possible type of the parameter as an XML qualified name, + defaults to xs:string. It SHOULD specify the type of a single optional value. Multiple options + with the same type but different values SHOULD specify a set of possible values which are + acceptable as input for the parent parameter.

+
+ + +
mediaType
+
+

The "mediaType" attribute indicates that the parent parameter acts as a media type selector + for requests or responses. The value of the attribute is the media type that is expected. If + a representation of an OPTIONAL media type is exposed, this representation can act as a + template for manipulating a resource.

+
+ + +
link
+
+

The "link" attribute is used to identify links to resources. It can have the value local, remote, + or list. A local link links to another resource located at the same server entity. A remote link links to + a resource located at another server entity anywhere in the XMPP network overlay. A link with a + list value indicates a list of remote links that can be used for discovery or linking to a set + of resources.

+
+ +
+ + + +

In order to access a resource, the &IQ; stanza type "set" has to be used. The returned + &IQ; stanza is either of type "error" or "result". If it is of type "result", the returned content has to be + complied with the xml-rest schema of this specification. The xml-rest schema has been designed + for providing a xml-rest encoded payload for accessing a resource. + An &IQ; stanza MUST NOT contain more than one method element with one request and one response. + The following example illustrates how the create method of the previous example is requested. + Here, the client requests three VMs which are based on an image that is available as resource + on the client's side.

+ + + + + + + + requester@company-b.com/rest-client + /images/myLinuxImage + + + + 3 + + + + + + + + + + + ]]> +

In order to make sure that both parties have a common understanding, the requester specifies also + the expected responds type which has been exposed during the exploration step. The counter party has to + answer such a request with the same request element and an extended complitation of the response + element as illustrated in the example below. +

+ + + + + + + + requester@company-b.com/rest-client + /images/myLinuxImage + + + + 3 + + + + + + + dc1.company-a.com/openstack + requester/vms/vm1 + + + dc2.company-a.com/openstack + requester/vms/vm02 + + + dc3.company-a.com/openstack + requester/vms/vm003 + + + + + + + + ]]> +

The following subsections describe each component of a xml-rest document in detail.

+ +

The "resource" element forms the root of an xml-rest document and MUST comprise only a + single "method" sub-element. In contrast to the xwadl description, no further documentation or grammers + are possible in order to keep the number of bytes as low as possible. + In order to specify the resource to access, the "path" attribute is required.

+ + +

The "method" element MUST have one request element and one response element. Additionally, the + "name" attribute is required in order to identify the action that has to be performed on the resource.

+ + +

The "request" and the "response" element are according to the xml-rest schema of type "call". They are + identical by definition and including the information for applying the method of a resource. + Both elements have no attributes and may contain one or more "param" elements as child elements.

+
    +
  • A request includes the input data to the method as a collection of parameters.
    • +
  • A response includes the output data to the method as a collection of parameters.
    • +
+ + +

Each "param" element has a "name" attribute to identify the parameter and a single sub-element + that includes the data. Possible sub-elements are value, representation, link, or resourceList.

+ + +

The "value" element has a "type" attribute that specifies the type of the value.

+ + +

The "representation" element has a "mediaType" attribute that specifies the media type of the representation.

+ + +

A "link" element or a "resourceList" element have no attributes. While a link targets to a single local + or remote location, a resource list is a set of links which are targeting to any resource in an XMPP + overlay network. A link can be expressed in two forms: as XMPP resource link with a "to" + (e.g. <to>requester@company-b.com/rest-client</to>) and a "path" (e.g. + <path>/images/myLinuxImage</path>) element + or as URI (<uri>xmpp://requester@company-b.com/rest-client?/images/myLinuxImage</uri>).

+ + + + + +

The REST with XMPP protocol enables a multi-dimensional resource placement. The following examples show + how different resources can be placed within a single server entity:

+ + + ... + + + ]]> + + + ... + + + ]]> + + + ... + + + ]]> + + + ... + + + ]]> + + + ... + + + ]]> +

All examples above are accessing different resources. A variation of the path attribute of the resource + element would also combine the presented JIDs and referring to different resources. + Further examples are possible to show how different resources can be located at a single server entity.

+ + + +

If an entity supports the REST with XMPP protocol, it SHOULD advertise that fact in response to &xep0030; information ("diso#info") requests by returning an identity of "automation/rest" and a feature of "jabber:iq:rest":

+ + + + ]]> + + + + + + + ]]> + + +

Determining when and how a resource can be accessed or modified based on permissions or + rights are considered outside the scope of this document. Although such mechanisms SHOULD be + considered specifically to the application and/or implementation of this document, + future specifications may address these concerns.

+ + +

REQUIRED.

+ + + +

The ®ISTRAR; includes 'urn:xmpp:rest:xwadl' and 'urn:xmpp:rest:xml' in its registry of protocol namespaces.

+ + +

The XMPP Registrar includes a Service Discovery type of "rest" within the "automation" category in its registry of service discovery identities.

+ + + + + + + + + + + The protocol documented by this schema is defined in + XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + + + + + + + The protocol documented by this schema is defined in + XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + diff --git a/inbox/userrating.xml b/inbox/userrating.xml index 9e867e82..3376dbaf 100644 --- a/inbox/userrating.xml +++ b/inbox/userrating.xml @@ -1,229 +1,229 @@ - - -%ents; -]> - - -
- User Rating - This specification provides for the rating element. - - This XMPP Extension Protocol is copyright (c) 1999 - 2014 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - xxxx - ProtoXEP - Standards Track - Standards - Council - - XMPP Core - - - - NOT_YET_ASSIGNED - - Daniel - Wisnewski - daniel.wisnewski@tigase.org - daniel@tigase.org - - - 0.0.1 - 2016-05-21 - dsw -

First draft.

 - -
- -

With the growing prevalence of XMPP communications, it is no longer safe to assume that XMPP will be free of spammers and nuisance users due to its obscurity. To that effect, this protocols aim is to create a user rating that can be used to hinder unnecessary communication within servers. While there have been several attempts to curb spam within servers, they have targeted the specific messages that may be labeled as spam, or relied on blocking policies. This approach singles out the JID of the user to (hopefully) remove their access to the server.

- - -

XMPP Core, not known at this point.

- - -

A user rating is an integer value assigned to a user’s bare JID to aid servers in determining JIDs that are predisposed to spam or offensive messages. The User Rating allows servers to determine appropriate actions from limiting stanza sending, to kicking or banning of the JID from the server. The rating, once implemented can be used in automated and user-based environments to curb abusive users. - element should be attached to a bare JID and should contain a float. - 0.0]]> - Would indicate the user is behaving normally, and is not suspected of sending spam. Where a user who has achieved a rating of the following: - 1.0 would be kicked from the server, for example. - is the JID of the user to be reported for spam or abuse. ]]>

- - - - A user may obtain their own rating by sending an IQ-get with no to address and an element qualified by the ‘rating’ namespace. - - - - ]]> - The server should return an IQ result stanza with element: - - - 0.1 - - - ]]> - - - In installations that run as chat servers, moderation of spam users can be delivered to online users and administrators. Users receiving spam from a bare JID can send an IQ stanza to the server that increases the user rating. - - - mercutio@shakespeare.lit - - ]]> - -

- To report abuse, an IQ stanza must be sent with the set type including the - repored-jid element. If montague.net happens to a local vhost server, then it - will be processed by that server. However, this stanza would be sent directly - to montague.net with the rating payload. -

- - ]]> -

Server sends a result IQ to confirm receipt of the report.

-

- Servers should notify a user JID that they have been reported, however the - identity of the reporter MUST remain anonymous, therefore the message - should be sent from the server itself. -

- - - Your actions have been reported as spam, and your rating has been increased. - ]]> - -

Server should return a not supported stanza if rating is not supported.

- - - - - - - - ]]> -

- Local server may be programmed to create a <rating/> locally and - track communications on its own server if this result is returned. -

-

- Server should return a not found stanza if the JID specified in - <reported-jid/> is unable to be found: -

- - - - - - - - ]]> -

A message should be sent to inform user that the JID is not found:

- - The reported user JID has not been found on this server. - - ]]> -

- Whether the jid is of a local or foreign domain, the montague.net server - should at this point begin to track the reported jid - mercutio@shakespeare.lit and a new user rating. -

-

- JIDs that are critical to server functionality or admins should have a - permanent of -100 to indicate that they are protected. Should a - user attempt to report a protected user, the server should send the - following: -

- - - - - - - - ]]> -

- The server may report the error with a message to the original user, - indicating that the selected <reported-jid/> is admin or protected. -

-

- When a user is found ‘guilty’ of being a spammer using this method the - server should first deliver a message before action is taken: -

- - You have been found to be spamming the montague.net server, please take some time and cool off. - - ]]> -

- The server will then conduct appropriate action, either a kick, or an - outright ban depending on the severity of the offenses, or settings within - the server. Actions may be taken using existing XEP-0061 Privacy Lists or - XEP-0191 Blocking Command, or an internal implementation to prevent - communication from known spammer accounts. -

- - - -

OPTIONAL.

- - -

element may be incorporated into non-human based systems as well. Unexpected JIDs, or ones that connect externally may be automatically given a high rating, and the server set for a low tolerance of stanzas sent in, allowing for quick and generally automated expulsion of unwanted or abusive JIDs from an automated system. The element does not require a human interaction, instead it can be manipulated by a host server for automated abuse control. - Depending on a server operator’s level of forgiveness, ratings may be permanent or can normalize to 0 after a period of time.]]>

- - -

- This feature may lend itself to abuse from users who wish to punish or abuse - another user. All rating systems should follow two abuse control rules to - limit abuse potential: -

-
    -
  1. - No one entity can use the rating system to ban/kick a JID unless they are - a server administrator. There must at least two or more JIDs reporting - spam or abuse to pass the kick or ban threshold. -
    2. -
  2. - Successive report values on same JID will decrease in weight against a - user rating, eventually lowering to zero (which then can be marked as - spam/abuse). For example: the first <repored-jid/> of - mercutio@montague.net by Romeo@montague.net increases the rating by 0.1. - The second from romeo@montague.net the same user is now weighted slightly - less, by increasing it 0.08. The third 0.06, fourth 0.04 and so on until - the weighted value of the report is null. At this point, it would be - advisable to notify Romeo that he is abusing the rating system, and will - begin to increase his own rating by further pushing the issue. -
    3. -
  3. - Critical or known-user JIDs exempt from rating rules should be set to a - value such as -100 to indicate that they are exempt from spam control - measures. -
    4. -
- - -

This document requires no interaction with the Internet Assigned Numbers Authority (IANA).

- - -

None known at this point.

- - -

Not finished at this point.

- - + + +%ents; +]> + + +
+ User Rating + This specification provides for the rating element. + + This XMPP Extension Protocol is copyright (c) 1999 - 2014 by the XMPP Standards Foundation (XSF). + Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. + ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## + In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. + This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). + + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + + + + NOT_YET_ASSIGNED + + Daniel + Wisnewski + daniel.wisnewski@tigase.org + daniel@tigase.org + + + 0.0.1 + 2016-05-21 + dsw +

First draft.

 + +
+ +

With the growing prevalence of XMPP communications, it is no longer safe to assume that XMPP will be free of spammers and nuisance users due to its obscurity. To that effect, this protocols aim is to create a user rating that can be used to hinder unnecessary communication within servers. While there have been several attempts to curb spam within servers, they have targeted the specific messages that may be labeled as spam, or relied on blocking policies. This approach singles out the JID of the user to (hopefully) remove their access to the server.

+ + +

XMPP Core, not known at this point.

+ + +

A user rating is an integer value assigned to a user’s bare JID to aid servers in determining JIDs that are predisposed to spam or offensive messages. The User Rating allows servers to determine appropriate actions from limiting stanza sending, to kicking or banning of the JID from the server. The rating, once implemented can be used in automated and user-based environments to curb abusive users. + element should be attached to a bare JID and should contain a float. + 0.0]]> + Would indicate the user is behaving normally, and is not suspected of sending spam. Where a user who has achieved a rating of the following: + 1.0 would be kicked from the server, for example. + is the JID of the user to be reported for spam or abuse. ]]>

+ + + + A user may obtain their own rating by sending an IQ-get with no to address and an element qualified by the ‘rating’ namespace. + + + + ]]> + The server should return an IQ result stanza with element: + + + 0.1 + + + ]]> + + + In installations that run as chat servers, moderation of spam users can be delivered to online users and administrators. Users receiving spam from a bare JID can send an IQ stanza to the server that increases the user rating. + + + mercutio@shakespeare.lit + + ]]> + +

+ To report abuse, an IQ stanza must be sent with the set type including the + repored-jid element. If montague.net happens to a local vhost server, then it + will be processed by that server. However, this stanza would be sent directly + to montague.net with the rating payload. +

+ + ]]> +

Server sends a result IQ to confirm receipt of the report.

+

+ Servers should notify a user JID that they have been reported, however the + identity of the reporter MUST remain anonymous, therefore the message + should be sent from the server itself. +

+ + + Your actions have been reported as spam, and your rating has been increased. + ]]> + +

Server should return a not supported stanza if rating is not supported.

+ + + + + + + + ]]> +

+ Local server may be programmed to create a <rating/> locally and + track communications on its own server if this result is returned. +

+

+ Server should return a not found stanza if the JID specified in + <reported-jid/> is unable to be found: +

+ + + + + + + + ]]> +

A message should be sent to inform user that the JID is not found:

+ + The reported user JID has not been found on this server. + + ]]> +

+ Whether the jid is of a local or foreign domain, the montague.net server + should at this point begin to track the reported jid + mercutio@shakespeare.lit and a new user rating. +

+

+ JIDs that are critical to server functionality or admins should have a + permanent of -100 to indicate that they are protected. Should a + user attempt to report a protected user, the server should send the + following: +

+ + + + + + + + ]]> +

+ The server may report the error with a message to the original user, + indicating that the selected <reported-jid/> is admin or protected. +

+

+ When a user is found ‘guilty’ of being a spammer using this method the + server should first deliver a message before action is taken: +

+ + You have been found to be spamming the montague.net server, please take some time and cool off. + + ]]> +

+ The server will then conduct appropriate action, either a kick, or an + outright ban depending on the severity of the offenses, or settings within + the server. Actions may be taken using existing XEP-0061 Privacy Lists or + XEP-0191 Blocking Command, or an internal implementation to prevent + communication from known spammer accounts. +

+ + + +

OPTIONAL.

+ + +

element may be incorporated into non-human based systems as well. Unexpected JIDs, or ones that connect externally may be automatically given a high rating, and the server set for a low tolerance of stanzas sent in, allowing for quick and generally automated expulsion of unwanted or abusive JIDs from an automated system. The element does not require a human interaction, instead it can be manipulated by a host server for automated abuse control. + Depending on a server operator’s level of forgiveness, ratings may be permanent or can normalize to 0 after a period of time.]]>

+ + +

+ This feature may lend itself to abuse from users who wish to punish or abuse + another user. All rating systems should follow two abuse control rules to + limit abuse potential: +

+
    +
  1. + No one entity can use the rating system to ban/kick a JID unless they are + a server administrator. There must at least two or more JIDs reporting + spam or abuse to pass the kick or ban threshold. +
    2. +
  2. + Successive report values on same JID will decrease in weight against a + user rating, eventually lowering to zero (which then can be marked as + spam/abuse). For example: the first <repored-jid/> of + mercutio@montague.net by Romeo@montague.net increases the rating by 0.1. + The second from romeo@montague.net the same user is now weighted slightly + less, by increasing it 0.08. The third 0.06, fourth 0.04 and so on until + the weighted value of the report is null. At this point, it would be + advisable to notify Romeo that he is abusing the rating system, and will + begin to increase his own rating by further pushing the issue. +
    3. +
  3. + Critical or known-user JIDs exempt from rating rules should be set to a + value such as -100 to indicate that they are exempt from spam control + measures. +
    4. +
+ + +

This document requires no interaction with the Internet Assigned Numbers Authority (IANA).

+ + +

None known at this point.

+ + +

Not finished at this point.

+ + diff --git a/xep-0323.xml b/xep-0323.xml index 3cfa27c2..af91beab 100644 --- a/xep-0323.xml +++ b/xep-0323.xml @@ -1,4 +1,4 @@ - + %ents; diff --git a/xep-0324.xml b/xep-0324.xml index 9fd52b7e..f7f55c5a 100644 --- a/xep-0324.xml +++ b/xep-0324.xml @@ -1,4 +1,4 @@ - + %ents; diff --git a/xep-0325.xml b/xep-0325.xml index 3a43a016..f7eac2eb 100644 --- a/xep-0325.xml +++ b/xep-0325.xml @@ -1,4 +1,4 @@ - + %ents; diff --git a/xep-0331.xml b/xep-0331.xml index 12172c08..b26813c5 100644 --- a/xep-0331.xml +++ b/xep-0331.xml @@ -1,4 +1,4 @@ - + %ents; diff --git a/xep-0332.xml b/xep-0332.xml index d7d53be5..19ea0d4e 100644 --- a/xep-0332.xml +++ b/xep-0332.xml @@ -1,4 +1,4 @@ - + %ents; diff --git a/xep-0347.xml b/xep-0347.xml index 55b24a6a..d6b9adad 100644 --- a/xep-0347.xml +++ b/xep-0347.xml @@ -1,4 +1,4 @@ - + diff --git a/xep-0348.xml b/xep-0348.xml index c80e46fe..aeaab22f 100644 --- a/xep-0348.xml +++ b/xep-0348.xml @@ -1,4 +1,4 @@ - + %ents;