== REST API ==
* The [http://en.wikipedia.org/wiki/REST#RESTful_web_APIs REST API] will be implemented as a first-class citizen
** It provides all the available functions and data to its clients
** Serves as a data and business logic abstraction layer
* The REST API will be implemented using HTTPS and REST principles
** Clients are required to validate the certificate (at least via CA)
* The REST API uses JSON as the primary data interchange format (serialization of data structures should be abstracted), other formats should be possible in the future.
* Authentication via Basic HTTP-Auth
* Multiple authentication methods can be added in the future (possibly Web-Server assisted):
** X509 Certificate based authentication
** Kerberos
** API key with shared secret
** Access tokens
** OAuth
* versioned API:
** starting with one version number in the URI, for example: https://api.selfcare.com/v1/customer , corresponding to the major version in SemVer
** minor version will be added via Request-Header-Field in future (as-needed)
* All API calls need to be fully nonblocking. If an expensive call has to be made to a backend system, the client needs to be provided with a status URI which can be checked for the current status or preferably be notified via [http://en.wikipedia.org/wiki/WebSocket WebSockets].
* Input validation must be performed for all data (validation of data happens twice: in the API and the client)
** JSON (or XML) validation has to be done before everything else and the client needs to be informed if he passed invalid syntax (see [http://www.php.net/manual/de/function.json-last-error.php function.json-last-error] and [http://www.php.net/manual/de/function.json-last-error-msg.php function.json-last-error-msg])
* Meaningful error message will be presented to the client
* All API functions are to be documented using an accepted documentation standard (doxygen (preferred), phpDocumentor or Sami)
* The API will be based on existing, proven and tested open source modules and components, coming either from a framework are as stand alone implementations,
Why a REST API?
* Separation and abstraction of presentation and business logic
** Faster development/test cycles for business logic
** Smaller development packages
* Support for multiple clients with the same code base
** HTML/JS/CSS for selfcare Web GUI
** Command line interface for easy scripting
** Integration into third party provisioning systems for resellers
* Automatic testing of functionality
* Base for [http://en.wikipedia.org/wiki/Responsive_web_design responsive] resp. [http://www.abookapart.com/products/mobile-first Mobile First] Web-Applications/-Design
=== Yii related API modules ===
* On the Yii PHP Framework Homepage: [http://www.yiiframework.com/extensions/?tag=rest Extensions tagged with "rest"]
** On the Yii PHP Framework Homepage: [http://www.yiiframework.com/extension/restfullyii/ RestfullYii] or on GitHub: [https://github.com/evan108108/RESTFullYii RestfullYii]
* On the Yii PHP Framework Homepage: [http://www.yiiframework.com/extensions/?tag=api Extensions tagged with "api"]
* [http://www.yiiframework.com/extension/yii-apiauth/ yii-apiauth]
== Service implementation details ==
=== Base URI ===