Revision as of 11:17, 30 January 2014

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 [:Category:Self-Service Modules|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?

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