stoney core: REST API (Technical Requirements and Implementation)
From stoney cloud
Why a REST API?
- 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.
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
- API key with shared secret
- Access tokens
- 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: 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?
- services vs. products
- product UIDs vs. names (
REST API Implementation
Yii related API modules: