stoney core: REST API (Technical Requirements and Implementation)

From stoney cloud
Jump to: navigation, search

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:

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)
  • 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 UIDs vs. names (mail/12345678 vs. mail/example.com)
    • Maybe both should work? If not, uid would be preferable, as they stay fix, even if you rename the mail account. --Michael (talk) 09:47, 30 January 2014 (CET)

REST API Implementation

Yii related API modules:

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