Difference between revisions of "stoney core: REST API"

[unchecked revision]

Revision as of 13:27, 17 October 2013

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
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.
Multiple authentication methods are possible
- Web-Server assisted:
  - Basic HTTP-Auth
  - X509 Certificate based authentication
  - Kerberos
- API key with shared secret
- Access tokens
versioned API (either via URI or the Accept-Header)
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,

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

On the Yii PHP Framework Homepage: Extensions tagged with "rest"
- On the Yii PHP Framework Homepage: RestfullYii or on GitHub: RestfullYii
On the Yii PHP Framework Homepage: Extensions tagged with "api"

@@ Line 13: / Line 13: @@
 ** Access tokens
 * versioned API (either via URI or the Accept-Header)
-* 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
+* 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)
 * Meaningful error message will be presented to the client