Difference between revisions of "stoney core: REST API (Technical Requirements and Implementation)"
From stoney cloud
[unchecked revision] | [checked revision] |
(→Yii related API modules) |
(→Why a REST API?) |
||
(9 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | = | + | = Why a REST API? = |
+ | Separation and abstraction of presentation ([[:Category:Self-Service Modules|Self-Service Modules]]) and business logic ([[:Category:Mapping (REST - LDAP)|Mapping (REST - LDAP)]]). | ||
+ | * Faster development and test cycles for the business logic. | ||
+ | * Smaller development packages. | ||
+ | * Distribution of development packages to different suppliers. | ||
+ | |||
+ | Support for multiple clients with the same code base: | ||
+ | * HTML/JS/CSS for [[:Category:Self-Service Modules|Self-Service Modules]] like [[:Category:stoney conductor|stoney conductor]] or [[:Category:stoney backup|stoney backup]]. | ||
+ | * Command line interface (CLI) for easy scripting. | ||
+ | * Integration into third party provisioning systems for resellers and partners. | ||
+ | |||
+ | Automatic testing of functionality. | ||
+ | |||
+ | Base for [http://en.wikipedia.org/wiki/Responsive_web_design responsive] respectively [http://www.abookapart.com/products/mobile-first Mobile First] Web-Applications/-Design. | ||
+ | |||
+ | = REST API Requirements = | ||
+ | * 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 [http://en.wikipedia.org/wiki/REST#RESTful_web_APIs REST API] will be implemented as a first-class citizen | * 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 | ** It provides all the available functions and data to its clients | ||
Line 23: | Line 43: | ||
* 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, | ||
+ | == stoney vm == | ||
+ | <pre> | ||
+ | stoney vm: Virtual Machines Resource - REST API | ||
− | + | https://api.example.com/v1/services/vm | |
− | + | https://api.example.com/v1/services/vm/vms | |
− | + | https://api.example.com/v1/services/vm/vms/3712345 | |
− | + | </pre> | |
− | + | * How do we handle actions (start/stop/...)? | |
− | + | * How can we avoid polling? | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
+ | == Notes == | ||
+ | * services vs. products | ||
+ | ** Product: stone mail, stoney vm, stoney backup --[[User:Michael|Michael]] ([[User talk:Michael|talk]]) 09:47, 30 January 2014 (CET) | ||
+ | ** Service: mail domains and accounts, backup accounts, virtual machines (as defined in the directory under ou=services https://api.example.com/v1/services/vm/vms | ||
+ | * product UIDs vs. names (<code>mail/12345678</code> vs. <code>mail/example.com</code>) | ||
+ | ** Maybe both should work? If not, uid would be preferable, as they stay fix, even if you rename the mail account. --[[User:Michael|Michael]] ([[User talk:Michael|talk]]) 09:47, 30 January 2014 (CET) | ||
− | == | + | = REST API Implementation = |
+ | 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] | ||
Line 44: | Line 70: | ||
− | [[Category: Development]][[Category:REST API]] | + | [[Category: Development]][[Category:REST API]][[Category:stoney core]] |
Latest revision as of 13:50, 15 May 2014
Contents
Why a REST API?
Separation and abstraction of presentation (Self-Service Modules) and business logic (Mapping (REST - LDAP)).
- Faster development and test cycles for the business logic.
- Smaller development packages.
- Distribution of development packages to different suppliers.
Support for multiple clients with the same code base:
- HTML/JS/CSS for Self-Service Modules like stoney conductor or stoney backup.
- Command line interface (CLI) for easy scripting.
- Integration into third party provisioning systems for resellers and partners.
Automatic testing of functionality.
Base for responsive respectively Mobile First Web-Applications/-Design.
REST API Requirements
- 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)
- JSON (or XML) validation has to be done before everything else and the client needs to be informed if he passed invalid syntax (see function.json-last-error and 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,
stoney vm
stoney vm: Virtual Machines Resource - REST API https://api.example.com/v1/services/vm https://api.example.com/v1/services/vm/vms https://api.example.com/v1/services/vm/vms/3712345
- How do we handle actions (start/stop/...)?
- How can we avoid polling?
Notes
- services vs. products
- Product: stone mail, stoney vm, stoney backup --Michael (talk) 09:47, 30 January 2014 (CET)
- Service: mail domains and accounts, backup accounts, virtual machines (as defined in the directory under ou=services https://api.example.com/v1/services/vm/vms
- product UIDs vs. names (
mail/12345678
vs.mail/example.com
)
REST API Implementation
Yii related API modules:
- 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"
- yii-apiauth