Difference between revisions of "stoney core: REST API (Technical Requirements and Implementation)"

From stoney cloud
Jump to: navigation, search
[unchecked revision][unchecked revision]
(→‎REST API)
(→‎REST API)
Line 1: Line 1:
−
== REST API ==
+
= Why a REST API? =
 +
Separation and abstraction of presentation ([[:Category:Self-Service Modules|Self-Service Modules]]) and business logic ([[:Category:Mapping (LDAP - JSON)|Mapping (LDAP - JSON)]]).
 +
* 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
 +
 
 +
= REST API =
 
* Non-Core API's must be able to be added without modifying the core-API.
 
* Non-Core API's must be able to be added without modifying the core-API.
 
* Repository organisation:
 
* Repository organisation:
Line 28: Line 42:
 
* 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,
 
* 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,
  
−
 
+
= Yii related API modules =
−
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/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/extension/restfullyii/ RestfullYii] or on GitHub: [https://github.com/evan108108/RESTFullYii RestfullYii]

Revision as of 14:04, 30 December 2013

Why a REST API?

Separation and abstraction of presentation (Self-Service Modules) and business logic (Mapping (LDAP - JSON)).

  • 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 responsive resp. Mobile First Web-Applications/-Design

REST API

  • Non-Core API's must be able to be added without modifying the core-API.
  • Repository organisation:
    • One repository per resource?
    • Access to the the repositories?
  • The 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 WebSockets.
  • Input validation must be performed for all data (validation of data happens twice: in the API and the client)
  • 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,

Yii related API modules

Retrieved from "http://wiki.stoney-cloud.org/mediawiki/index.php?title=stoney_core:_REST_API_(Technical_Requirements_and_Implementation)&oldid=2562"