thekid/rfc — Issue #17: RFC 0017: Webservices metadata
Author: thekid
Created: 2011-10-09 14:09:28+00:00
State: open

Scope of Change
====
The webservices APIs (xml.xmlrpc and xml.soap.rpc) will be unified into
one API which makes use of the new metadata facility described in
xp-framework/rfc #16.

Rationale
====
With annotations, the following will be possible:

* Declare methods as invocable by means of the client (public modifier
is not sufficient).

* Add details about service name, binding type, targetNamespace and
others to enable easy WSDL generation.

* Add access control based on methods, not on the entire webservice.

Functionality
====
The webservice tag marks a class as being a web service. The webmethod
tags identify those methods that are exposed externally as web service
operations.

```php

```

Access control
----
You can protect *entire* webservices by using your web server's
authentication models (e.g. Basic Authorization via .htaccess in Apache)
but cannot protect selective methods.

The functionality will be (in part) implemented by using metadata. This
way, a service developer can define access control for critical methods.

Methods that should be restricted are given a "restricted" annotation
defining which role a user must have to invoke this method.

Example:

```php

```

In case restricted methods are tried to be invoked without authentication,
the web service should answer with HTTP 401 ("Authentication required").

The deployer (which may be in fact the same person) will now have to
map the "admin" role to the exact users.

WSDL mapping annotations
----
Note: This section only applies to SOAP RPCs, not to XMLRPC.

Example:

```php

```

- The webservice name is mapped to the wsdl:portType and defaults to
the simple name of the class stripped of the word "Handler".

- The webmethod name is mapped to the wsdl:operation name and defaults
to the method's name. The SOAPAction is generated from the class name
and method name to allow easy reflection.

Resulting WSDL:

```

```

Dependencies
====
- xp-framework/rfc #16
- A new package "webservices".

Related documents
====
- Web Services Metadata for the Java[TM] Platform
http://jcp.org/en/jsr/detail?id=181

- WSDL example: Google search
http://api.google.com/GoogleSearch.wsdl

- @webmethod implementation
http://xp-framework.net/downloads/rpc.diff

Comments
====
- friebe, Fri Feb 11 19:45:50 CET 2005
How should the account -> role mappings be realized?

- friebe, Fri Feb 11 19:46:18 CET 2005
How do different SOAP client react to HTTP 401? Is there a standard
defining how "access denied" should be represented?

- friebe, Sat Feb 12 13:45:37 CET 2005
This requires class annotations

- friebe, Sun Feb 13 18:56:41 CET 2005
Changing this RFC to also include API unification. That way, we can
use common subclasses for both - the authentication mechanism should
not be implemented twice (or once and then be copy&pasted).

- friebe, Mon Feb 28 17:53:10 CET 2005
In the first step, only @webmethod will be supported - and the API
will stay as-is. Too much BC involved at the moment.